Welcome

©1997-1999 Quiksoft Corporation.
All Rights Reserved.
Unauthorized duplication
or distribution prohibited.

Documentation Last Updated: April 29, 1999


Version 4.5

What's New in Version 4.5

EasyMail Objects 4.5 is an incremental upgrade to version 4.0. This page describes only what's new in version 4.5. Version 4.0 added much functionality over prior versions. Click here to see the new features added in version 4.0.

Mail Dialogs

The EasyMail Objects now support dialogs for composing and viewing e-mail messages. The dialog functionality is totally encapsulated inside a seperate dialog module dll. By seperating the dialog functionality into another dll, we were able to keep the core objects small and lightweight.

Install the dialog module and your application can display rich e-mail dialogs with one line of code.

See the section on Mail Dialogs for more information.

MessagePrinter Object

The new EasyMail MessagePrinter object, allows you to easily send an e-mail message to a system printer.

See the section on MessagePrinter for more information.

Object Data Exchange (ODE)

Transferring message data from one object to another is now just as simple as one line of code. Retrieve a message with the POP3 or IMAP4 object and transfer it into the SMTP object for sending replies, forwards etc...

See the following section on each object for the new methods that make ODE possible.

SMTP Object Enhancements

PerformanceMode Property | Controls threading options.
AddAttachmentEx() Method | Adds an attachment to the message with custom MIME part headers and other options.
Cancel() Method | Cancels the transmission of the message currently being sent.
DoSendDlg() Method | Displays a message composition / editing dialog.
LoadMessageFromHandle() Method | Loads message data from a handle generated by another object such as the POP3 or IMAP4 objects.
Progress() Event | Indicates the progress of a message being sent.

IMAP4 Object Enhancements

CreateMessageHandle() Method (Message Object) | Creates a message handle representing the current message.
DoViewDlg() Method (Message Object) | Displays a dialog with the current message loaded for viewing.

POP3 Object Enhancements

CreateMessageHandle() Method (Message Object) | Creates a message handle representing the current message.
DoViewDlg() Method (Message Object) | Displays a dialog with the current message loaded for viewing.

If you are upgrading from a release prior to version 4, click here to find out what was added in version 4.

If you are upgrading from a release prior to version 3, click here to find out what was added in version 3.


Upgrading

If you have purchased a license key for the EasyMail Objects prior to version 4, a new license key will be required for version 4.5.

If you purchased a license key for version 4, your license key will work with version 4.5 and there is no cost to upgrade.

Please visit our web site for upgrade procedures and pricing.

http://www.quiksoft.com/easymail


Doc Errors and Updates

Documentation

Please report any error found within this documentation to documentation@quiksoft.com.


Support

Obtaining Support

Support for our products can be obtained from our web site, newsgroups or e-mail.

Newsgroups

Our newsgroups are an excellent place to find immediate answers to frequently asked questions. New questions posted on the newsgroups can be replied to by Quiksoft or other users. You can access our newsgroups by pointing your news reader to news.quiksoft.com.

Updates FAQs and Technical Documents

Our web site contains answers to frequently asked questions and update files. The address is http://www.quiksoft.com/support.

E-Mail

If you can not access our newsgroups and can not find the answer to your question on our web site, you may e-mail it to support@quiksoft.com.


Licensing and Registration

Licenses for the EasyMail objects may be purchased from Quiksoft Corporation.

When you purchase a license from Quiksoft, you will receive a license key. By assigning your license key to the object's LicenseKey property, you will take any "demo", restrictions off of the object.

When you license the EasyMail Objects, you will be permitted to distribute them with your applications royalty free. For all the details, see the Royalty Free License Agreement.


License Agreement

EASYMAIL OBJECTS ROYALTY FREE SOFTWARE LICENSE AGREEMENT

1. DEFINITIONS

a. ("QUIKSOFT") refers to Quiksoft Corporation.

b. ("LICENSEE") refers to the entity acquiring this license.

c. ("OBJECTS") refers to the EasyMail SMTP, EasyMail POP3, EasyMail IMAP4 and EasyMail MessagePrinter objects.

d. ("MODULES") refers to the EasyMail Dialog Module dll.

e. ("SOFTWARE") collectively refers to the OBJECTS, MODULES, LICENSE KEY and any associated documentation.

f. ("APPLICATION") refers to a computer program designed to utilize the SOFTWARE.

2. GRANT OF LICENSE. QUIKSOFT grants to the LICENSEE a non exclusive royalty free license to use the SOFTWARE on one computer. You may not network the SOFTWARE or otherwise use it on more than one computer at the same time.

3. DISTRIBUTION. QUIKSOFT grants to the LICENSEE a non exclusive royalty free license to distribute unlimited copies of the OBJECTS as an integral part of APPLICATIONs owned and copyrighted by the LICENSEE, providing that each APPLICATION adheres to the following conditions: (a) The APPLICATION may not compete with the SOFTWARE, (b) The APPLICATION may not expose the functionality of the SOFTWARE through a programmable interface. The LICENSE KEY may be embedded in distributed APPLICATIONs provided that the following conditions are met: (a) The APPLICATION must be marked with a prominent copyright notice bearing the name of the licensee as it appears in the LICENSE KEY. (b) The LICENSE KEY may not be embedded in an application which makes the LICENSE KEY visible to the end user. (c) The APPLICATION must include the following comment in its source code within close proximity to each copy of an embedded LICENSE KEY:

"This application utilizes a licensed copy of EasyMail Objects. EasyMail Objects is copyrighted and owned exclusively by Quiksoft Corporation. All rights reserved. Use of the objects outside of the context of this application is a violation of federal copyright laws and international treaty provisions."

4. COPYRIGHT. The SOFTWARE is owned by QUIKSOFT and is protected by United States copyright laws and international treaty provisions.

5. OTHER RESTRICTIONS. You may not rent or lease the SOFTWARE but you may transfer the SOFTWARE and accompanying written materials on a permanent basis provided you retain no copies and the recipient agrees to the terms of the agreement. You may not reverse engineer, decompile or disassemble the SOFTWARE. If the SOFTWARE is an update, any transfer must include the update and all prior versions in your possession.

6. PROPRIETARY RIGHTS. All copyright, patent, trade secret, trademarks and other intellectual and proprietary rights in the SOFTWARE are and shall remain the valuable property of QUIKSOFT, or the Author of the SOFTWARE. You agree to take all necessary steps to ensure that the provisions of this agreement are not violated by you or by any person under your control or in your service.

7. LIMITED WARRANTY. QUIKSOFT warrants that the SOFTWARE will operate substantially in accordance with its accompanying documentation for a period of thirty days from the date you receive it. This warranty is void if failure of the SOFTWARE has resulted from accident, abuse or misapplication. YOU ARE THE ONLY BENEFICIARY OF THIS WARRANTY. YOU MAY NOT PASS THIS WARRANTY ON TO OTHERS. Although QUIKSOFT has tested the SOFTWARE and reviewed the documentation, this SOFTWARE is licensed "AS IS" and you, the licensee, are assuming the entire risk as to its quality and performance.

8. CUSTOMER REMEDIES. The entire liability of QUIKSOFT and your exclusive remedy shall be, at the option of QUIKSOFT, either (a) return of the price paid or (b) replacement of the SOFTWARE. No warranty will be honored and remedy will be provided unless the SOFTWARE is returned to QUIKSOFT along with the original dated receipt. Any replacement SOFTWARE will be warranted for the remainder of the original warranty period or (30) days, whichever is longer. THESE REMEDIES ARE NOT AVAILABLE OUTSIDE THE UNITED STATES OF AMERICA.

9. NO LIABILITY FOR CONSEQUENTIAL DAMAGES. IN NO EVENT SHALL QUIKSOFT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTAL DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION, DAMAGES FOR BUSINESS INTERRUPTION, LOSS OF PROFITS OR DATA, OR OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE OR DOCUMENTATION EVEN IF QUIKSOFT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. QUIKSOFT SHALL HAVE NO LIABILITY FOR ANY DATA READ, ACCESSED, STORED OR PROCESSED WITH THE SOFTWARE, INCLUDING THE COSTS OF RECOVERING SUCH DATA. IN NO CASE SHALL QUIKSOFT'S LIABILITY EXCEED THE FEES PAID BY YOU FOR THE SOFTWARE. BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION OR EXCLUSION MAY NOT APPLY TO YOU.

10. GENERAL (a)If any provision of this agreement is found to be invalid by any court of competent jurisdiction, the balance of this agreement shall remain in full force and effect. (b)This agreement shall be governed by the laws of the State of Pennsylvania. Both you and QUIKSOFT consent to jurisdiction of the state and federal courts sitting in Delaware County, Pennsylvania, in connection with any suit or action brought regarding the SOFTWARE or this agreement. (c)This agreement is the complete and exclusive statement of the agreement by you and QUIKSOFT, It supersedes all prior communications between the parties relating to the subject matter of this agreement, whether written or oral. This agreement also supersedes the terms and conditions of any purchase order regarding the SOFTWARE, submitted in the past or to be submitted in the future. No QUIKSOFT dealer, agent or employee is authorized to make any modifications or additions to this agreement and warranty.


Purchase License

How to Purchase a License

Licenses may be purchased either on-line, by phone or by fax.

On-line secure server | https://www.quiksoft.com/order
Phone | 800-509-8700 / 610-544-3139
Fax | 610-544-5565
E-Mail | sales@quiksoft.com

For more purchasing information visit our web site at:

http://www.quiksoft.com/sales


What Is EasyMail

What Are the EasyMail Objects

The EasyMail Objects are a group of COM objects which contain the functionality to interface with the Internet e-mail system, and manage messages locally. The objects can easily be used by your application to compose, send, receive, display, print and manage Internet e-mail.

Object | Use
EasyMail SMTP | Composing and sending e-mail with SMTP (Simple Mail Transport Protocol)
EasyMail POP3 | Retrieving and managing e-mail with POP3 (Post Office Protocol 3)
EasyMail IMAP4 | Retrieving and managing e-maill with IMAP4 (Internet Message Access Protocol 4)
EasyMail MessagePrinter | Printing e-mail messages.

The objects were written in Visual C++ using ATL. The result is a set of extremely small, fast and efficient COM objects. The EasyMail Objects are designed to run on 32-Bit Windows implementations running on Intel processors. Each object is contained in its own DLL. The installation program places these DLLs in the Windows system directory.

Object | File Name
EasyMail SMTP Object | emsmtp.dll
EasyMail POP3 Object | empop3.dll
EasyMail IMAP4 Object | emimap4.dll
EasyMail MessagePrinter Object | emprint.dll

Each COM object can behave as in-process OLE automation server or as an OCX. Almost every development environment on the Windows platform supports the use of this type of object.

The EasyMail Objects work great with C, C++, ASP, Visual Basic, VB Script, VBA, Access, Internet Explorer, Pearl, Delphi, Power Builder and any other ActiveX/COM/OLE compatible development system.

Additional Modules

The EasyMail Objects also contain an additional module which contains the functionality necessary to display mail related dialog boxes. The dialog module is used by the EasyMail Objects internally and is not directly accessible by your application.

Module | File Name
EasyMail Mail Dialogs | emdialog.dll


Features

EASYMAIL SMTP OBJECT

The EasyMail SMTP Object is used for sending Internet e-mail using the Simple Mail Transport Protocol. It supports all the latest e-mail enhancements:

  • MIME formats including Base64 and quoted printable

  • HTML formatted message bodies
  • Binary attachments: Base64 or UUencoded
  • ESMTP (Extended SMTP) Pipelining
  • ESMTP (Extended SMTP) Delivery Status Notifications
  • Multiple Recipients, carbon copies and blind carbon copies
  • Ability to specify any character set such as US-ASCII, ISO8859-1, ISO-2022-JP, etc...
  • Supports backup SMTP servers
  • Ability to import message data from the POP3 or IMAP4 objects
  • Interfaces with the dialog module to display a mail composition dialog box
  • Progress notifications
  • Priority levels
  • Return receipts
  • Supports "Reply To"
  • Custom message and attachment headers
  • SMTP conversation logging
  • Windows NT event log integration
  • Message queuing

EASYMAIL POP3 OBJECT

The EasyMail POP3 object is used for retrieving Internet e-mail from a mail server running Post Office Protocol 3. Support is included for all the latest e-mail enhancements including:

  • MIME formats including Base64 and quoted printable

  • File Attachments: Base64 and UUencoded
  • APOP Authentication using RSA MD5
  • Ability to determine the character set used to compose the message, such as US-ASCII, ISO8859-1, ISO-2022-JP, etc...
  • Priority Levels
  • Reads custom header information
  • Ability to export message information to the SMTP object
  • Interfaces with the dialog module to display a dialog box for viewing a downloaded mail message
  • Progress notifications
  • POP3 conversation logging
  • Windows NT event log integration
  • All properties and methods available through a collection object interface

EASYMAIL IMAP4 OBJECT

The EasyMail IMAP4 object is used for retrieving Internet e-mail from a mail server running Internet Message Access Protocol 4. Support is included for all the latest e-mail enhancements including:

  • MIME formats including Base64 and quoted printable

  • File Attachments: Base64 and UUencoded
  • Shared folders
  • Folder management
  • Folder Subscribe/Unsubscribe
  • Access to all MIME parts
  • Envelope downloading
  • Message flags
  • IMAP4 notifications
  • Ability to determine the character set used to compose the message, such as US-ASCII, ISO8859-1, ISO-2022-JP, etc...
  • Priority Levels
  • Reads custom header information
  • Ability to export message information to the SMTP object
  • Interfaces with the dialog module to display a dialog box for viewing a downloaded mail message
  • Progress notifications
  • IMAP4 conversation logging
  • Windows NT event log integration
  • All properties and methods available through a collection object interface

EASYMAIL MESSAGEPRINTER OBJECT

The EasyMail MessagePrinter object allows you to easily send an e-mail message to a system printer.

  • Add a customizable header to the first page

  • Change the font and size of the message text
  • Change page margins
  • Print the current date and time on the bottom of each page
  • Print page numbers on the bottom of each page
  • Ability to preassign printers, dynamically select printers, or display the printer dialog and allow the user to select a printer at runtime.


Using the EasyMail Objects

Each object is 32-bit COM object that can behave as in-process OLE automation server or as an OCX. Almost every development environment on the Windows platform supports the use of this type of object.

In order to keep EasyMail small and fast, it does not carry a lot of the "visual" OCX control overhead. Because we do not include the "visual" overhead you will need to create the objects with a line of code, instead of dragging them from a toolbox onto a form. In any event, the EasyMail Objects can be used and programmed just as easily as any other control.

NOTE: The EasyMail Objects can display rich e-mail related dialogs with as little as one line of code. For more informaion see the section on MailDialogs.

The samples section of this documentation contains sample code snippets for various development systems. Outside of that section, Visual Basic is used as sample code throughout the documentation. This code can be easily adapted to other development systems.

To use the SMTP object in Visual Basic:

Dim SMTP As Object
Dim Result%
Set SMTP = CreateObject(EasyMail.SMTP.4")
SMTP.Subject = "RE: Product Information."
SMTP.BodyText = "Please send me product information."
... set other properties ...
Result = SMTP.Send()

Specific usage of each object is detailed in the reference section of this documentation. See:


License Keys

If you purchased a license key from Quiksoft, it must be correctly assigned to the LicenseKey property of the object. If the format of the license key is incorrect it will be ignored and the object will remain in demo mode.

Important Points to Remember

  • The license key is case sensitive.

  • The license key is unique to each licensee and product.
  • The LicenseKey parameter can not contain any line breaks
  • Your license key must be assigned to the LicenseKey property exactly as you received it without modification of any sort.
  • The LicenseKey property should be assigned to the object as soon as it is created.
  • The LicenseKey property must be set for all instances of the object.
  • A license key is not necessary for the MessagePrinter object.


Distributing the Objects

Note: Your license may restrict your rights to distribute the EasyMail Objects. Please check your license agreement before distribution the objects. If you are uncertain of your distribution rights, contact Quiksoft.

The runtime portion of the EasyMail Objects consist of 4 files, one for each object. These are the only files which need to be distributed. It is highly recommended that they be installed in the Windows system directory.

Object | File Name
EasyMail SMTP Object | emsmtp.dll
EasyMail POP3 Object | empop3.dll
EasyMail IMAP4 Object | emimap4.dll
EasyMail MessagePrinter Object | emprint.dll

The objects must be registered on each system where they are installed. See the section: Registering the Objects for more information.

If you are using the Mail Dialogs feature, then the dialog module must also be distributed.

Module | File Name
EasyMail Mail Dialog Module | emdialog.dll

The dialog module should not and can not be registered. The EasyMail Objects will try to load the dialog module from the following locations in order:

  1. The directory from which the application loaded.

  2. The current directory
  3. The system directory
  4. The Windows directory
  5. The directories which are listed in the PATH environment variable

The dialog module must be installed in one of these locations.


Registering the Objects

NOTE: This section explains how the EasyMail Objects are entered into the system registry. This should not be confused with registering the software with Quiksoft (i.e. sending in a registration card). Each object is automatically registered with Quiksoft at the time it is downloaded or purchased and no further registration is required.

Before, the EasyMail Objects can be used, they need to be registered. Registering the objects places entries in the system registry which allows the system to find the objects when it needs them. The EasyMail installation program does this for you automatically, however if you move the objects to another computer, they will have to be manually registered on that computer before they will work properly.

Objects are registered (and unregistered) with regsvr32.exe, a program which should be in your system directory. The registration process creates an entry in your system registry which cross references the CLSID, the ProgID, the type library and the actual location of the object on your system.

When you load an object by referring to its CLSID, or ProgID, the system registry is used to look up the actual location of the object (the DLL). If the object is not registered, the registry will not be able to provide the location and the object can not be loaded.

To correctly register an object, type:

regsvr32.exe d:\path\object.dll, where d:\path\object.dll is the full path and file name of the object to register. e.g.

regsvr32.exe c:\winnt\system32\emsmtp.dll

NOTE: If you will be running the object on a server, it is important that the object be installed and registered in a directory with proper access permissions. For more information on running the EasyMail objects on a server, see the section: A Note on Servers.


Running Objects on Windows NT Servers

Windows NT Servers

If you will be installing the EasyMail Objects on a Windows NT server, there are some important points to consider.

When the objects are running on a server, they will always be running in some security context. The security context must have read, and execute permissions in the directory where the objects are located.

IIS (Microsoft Internet Information Server)

If you are using the objects in an IIS application, the security context of the objects will be inherited from the IIS login account. All anonymous access to an IIS web server is logged in under an anonymous login account.

When IIS is installed, it creates an NT user account with the name IUSR_SERVER, where SERVER is the computer name of the server. This is the account which specifies the rights for anonymous users accessing the server.

If a user is logged on to a specific account, that is they are not accessing the web server anonymously, then the security context of the objects will be inherited from that account.

In order for the web server to load the object, it must be registered in a directory in which the security context, has read and execute access.

The EasyMail Objects installation program installs and registers the objects in the Widows system directory, which may not be appropriate for your setup. If necessary, you can move the object DLL files to a directory on the server in which the security context has read and execute access. You should register the objects there as well. See the section on registering the objects for more information.

Certain features of the objects may cause data to be written to disk. For example, the LogFile property of the SMTP Object or the TempDirectory property of the POP3 Main object. If an object needs to write to disk, the target directory must also have to have the proper access permissions set for the security context.

NOTE: If you are running the objects in an IIS application, which is set to run in its own address space, the security rights for the IWAM_<SERVER_NAME> account will be used instead of the IUSR_<SERVER_NAME> account for anonymous access.


Firewalls

Sending e-mail through a firewall requires that the firewall be setup to allow e-mail messages a free path to travel.

Remember that the TCP/IP connection is two-way. You will be sending information to the mail server and it will be sending status information back to you. Two ports will be involved in the conversation: the client's port and the server's port.

All ports below 1025 are reserved for use by specific protocols. Port 25 is reserved for SMTP mail servers, port 110 is reserved for POP3 mail servers and port 143 is reserved for IMAP4 mail servers. Since the client is not a mail server, it can not use port 25. Instead, the client system will usually automatically choose a port above 1024. The mail server will be conducting business on ports 25, 110 and 143.

Your firewall will have to allow outbound traffic from any internal port greater than 1024 to external ports 25, 110 and 143. Your firewall will also need to allow inbound traffic from external ports 25, 110 and 143 to any internal port greater than 1024.

The default server ports may be changed by specifying the desired port number in the MailPort property of the SMTP, POP3 or IMAP4 object. You will also need to adjusting the mail server to listen on those ports as well. It is not possible however to specify the client port .


About Samples

About the Samples

The samples provided in this section are not whole applications or programs. They consist of code snippets to demonstrate the use of the EasyMail Objects in various development environments.

We have tried to boil down the code as much as possible so that each sample clearly illustrates the use of the EasyMail Objects without the clutter of other operations.

These samples were designed to provide you with a starting point to understand how the EasyMail Objects can be used within your development environment.


ASP Notes

When using the EasyMail Objects with ASP, certain security rights must be established for the objects to function correctly.

See the topic: Windows NT Servers for more information.


Send a Message Using ASP and the SMTP Object

<%@ LANGUAGE="VBSCRIPT" %>
<html>
<head>
<title>EasyMail ASP Sample</title>
</head>

<body>
Sending mail...<BR><BR>
<%
Set SMTP = CreateObject("EasyMail.SMTP.4")

' change the following 6 property
' assignments to the correct information
SMTP.MailServer = "mail.yourdomain.com"
SMTP.Subject="subject"
SMTP.BodyText = "message"
SMTP.From = "Quiksoft EasyMail Test Form"
SMTP.FromAddr = "support@quiksoft.com"
SMTP.AddRecipient "John Doe", "jdoe@quiksoft.com", 1
x = SMTP.Send
%>
<% if x=0 then %>
   Your message has been sent.
<%else%>
   There was an error sending your mail.
<%end if%>
</body>
</html>


Send an HTML Message with Images (SMTP)

Send an HTML Message with Images Using ASP and the SMTP Object

This example creates an HTML message with two images. The code assumes that the image files are in the same directory as the ASP page.

Note: A license key is required for this example. The SMTP object can not send HTML messages in "demo" mode. For more information about composing HTML messages, see

 <%@ LANGUAGE="VBSCRIPT" %>
<%
SendMail

Sub SendMail
Set SMTP = CreateObject("EasyMail.SMTP.4")
SMTP.LicenseKey = "LICENSEE/CODE"
SMTP.FromAddr = "sender@somedomain.com"
SMTP.AddRecipient "", "recipient@somedomain.com", 1
SMTP.MailServer = "mail.somedomain.com"
'Set body format to HTML
SMTP.BodyFormat = 1
'Create image Attachment Headers
strHeaders = "Content-Id: <UniqueID>" & vbCrLf & _
             "Content-type: image/gif" & vbCrLf
ret=SMTP.AddAttachmentEx(Request.ServerVariables("APPL_PHYSICAL_PATH") & "image1.gif", strHeaders, 13 + 256)
If Not ret = 0 Then
   Response.Write  "Error Attaching File " & ret
   Exit Sub
End If
'Create Image 2 Attachment Headers
strHeaders = "Content-Id: <UniqueID2>" & vbCrLf & _
"Content-type: image/jpg" & vbCrLf
ret=SMTP.AddAttachmentEx(Request.ServerVariables("APPL_PHYSICAL_PATH") & "image2.gif", strHeaders, 13 + 256)
If Not ret = 0 Then
   Response.Write "Error Attaching File " & ret
   Exit Sub
End If
SMTP.BodyText="<body bgcolor=""White""><H1>Message Sample</H1><p>First image...<br><img src=""cid:UniqueID""></p><p>Second image...<br><img src=""cid:UniqueID2""></p>"
SMTP.Subject = "This is an html message with images."
ret = SMTP.Send()
If Not ret = 0 Then
   Response.Write  "Error Sending Message " & ret
   Exit Sub
End If
Response.Write  "Message sent successfully!"
End Sub
%>

Resulting Message Body

Sample Message

First image...

Second image...


Retrieve Mail using ASP and the POP3 Object

<%@ LANGUAGE="VBSCRIPT" %>
<html>
<head>
<title>EasyMail ASP Sample</title>
</head>

<body>
Checking mail...<BR><BR>
<%
Set POP3 = CreateObject("EasyMail.POP3.4")

' change the following 3 property
' assignments to the correct information
POP3.MailServer = "mail.yourdomain.com"
POP3.Account="jdoe"
POP3.Password="secret"

POP3.Connect
x=POP3.DownloadHeaders
%>
<% if x=0 then %>
   You have <%=POP3.Messages.Count%> messages waiting.
<%else%>
   There was an error retrieving your mail. Error code <%=x%>.
<%end if%>
<%
POP3.Disconnect
%>
</body>
</html>


Retrieve Mail using ASP and the IMAP4 Object

<%@ LANGUAGE="VBSCRIPT" %>
<html>
<head>
<title>EasyMail ASP Sample</title>
</head>

<body>
Checking mail...<BR><BR>
<%
Set IMAP4 = CreateObject("EasyMail.IMAP4.4")
x=IMAP4.Connect("mail.yourdomain.com")
x=IMAP4.Login("jdoe", "secret")
x=IMAP4.SelectMailbox("Inbox")
%>
<% if x=0 then %>
   You have <%=IMAP4.MessageCount%> messages waiting.
<%else%>
   There was an error retrieving your mail. Error code <%=x%>.
<%end if%>
<%
IMAP4.Logout
IMAP4.Disconnect
%>
</body>
</html>


Send a Message using Delphi and the SMTP Object

Enabling your Delphi application to send mail is as easy as 1, 2, 3. This sample is designed to work with Delphi 3 or later.

Step 1

Include the ComObj unit in your unit like this:

uses ComObj;

Step 2

Paste the following procedure into your application, enabling it to send e-mail.

procedure SendMail(const strMailServer, strFrom, strTo, strSubject, strBodyText: string);
var
   SMTP: Variant;
   nResult: Integer;
begin
   SMTP:=CreateOleObject('EasyMail.SMTP.4');
   SMTP.MailServer:=strMailServer;
   SMTP.FromAddr:=strFrom;
   SMTP.AddRecipient('', strTo, 1);
   SMTP.Subject:=strSubject;
   SMTP.BodyText:=strBodyText;
   nResult:=SMTP.Send;
   if nResult=0 then
      MessageDlg('Message sent successfully.', mtInformation, [mbOK], 0)
   else
      MessageDlg('There was an error sending your message.', mtInformation, [mbOK], 0)
end;

Step 3

Call the SendMail() procedure.

e.g.

SendMail('mail.yourdomain.com', 'fromname@yourdomain.com', 'toname@theirdomain.com', 'This is the subject', 'This is the message body text.');


Retrieve Mail using Delphi and the POP3 Object

Enabling your Delphi application to retrieve mail is easy. This sample is designed to work with Delphi 3 or later.

Step 1

Include the ComObj unit in your unit like this:

uses ComObj;

Step 2

Paste the following procedure into your application, enabling it to retrieve e-mail.

procedure DispMail(const strMailServer, strAccount, strPassword: string);
var
   POP3, Msgs, Msg: Variant;
   nCount, nResult, x: Integer;
begin
   POP3:=CreateOleObject('EasyMail.POP3.4');
   POP3.MailServer:=strMailServer;
   POP3.Account:=strAccount;
   POP3.Password:=strPassword;
   POP3.DemoMode:=1;
   nResult:=POP3.Connect;
   if nResult=0 then begin;
      nResult:=POP3.DownloadMessages(0);
      nCount:=POP3.Messages.Count;
      for x:= 1 to nCount do begin
         Msg:=POP3.Messages[x];
         MessageDlg('Subject = ' + Msg.Subject, mtInformation, [mbOK], 0);
      end;
   end;
   if nResult<>0 then
      MessageDlg('There was an error retrieving your mail.', mtInformation, [mbOK], 0);

   POP3.Disconnect;
end;

Step 3

Call the DispMail() procedure.

e.g.

DispMail('mail.yourdomain.com', 'jdoe', 'secret');


Retrieve Mail using Delphi and the IMAP4 Object

Enabling your Delphi application to retrieve mail is easy. This sample is designed to work with Delphi 3 or later.

Step 1

Include the ComObj unit in your unit like this:

uses ComObj;

Step 2

Paste the following procedure into your application, enabling it to retrieve e-mail.

procedure DispIMAPMail(const strMailServer, strAccount, strPassword, strFolder: string);
var
  IMAP4, Env: Variant;
  nCount, nResult, x: Integer;
begin
  IMAP4:=CreateOleObject('EasyMail.IMAP4.4');
  IMAP4.DemoMode:=1;
  nResult:=IMAP4.Connect(strMailServer);
  if nResult=0 then begin;
     nResult:=IMAP4.Login(strAccount, strPassword);
     if nResult=0 then begin;
        nResult:=IMAP4.SelectMailbox(strFolder);
        if nResult=0 then begin;
           nResult:=IMAP4.DownloadEnvelopes(0, -1, 0);
           if nResult=0 then begin;
              nCount:=IMAP4.Envelopes.Count;
              for x:= 1 to nCount do begin
                 Env:=IMAP4.Envelopes[x];
                 MessageDlg('Subject = ' + Env.Subject,
                             mtInformation, [mbOK], 0);
              end;
           end;
        end;
     end;
  end;
  if nResult<>0 then
     MessageDlg('There was an error retrieving your mail.',
                  mtInformation, [mbOK], 0);

  IMAP4.Disconnect;
end;

Step 3

Call the DispIMAPMail() procedure.

e.g.

DispIMAPMail('mail.yourdomain.com', 'jdoe', 'secret', 'Inbox');


Send a Message Using Visual Basic and the SMTP Object

The following function can be pasted into your Visual Basic application, enabling it to send e-mail.

Private Sub SendMail(strServer$, strFrom$, strTo$, strSubject$, strBodyText$)

   Dim x%
   Dim SMTP As Object

   Set SMTP = CreateObject("EasyMail.SMTP.4")
   SMTP.MailServer = strServer$
   SMTP.FromAddr = strFrom$
   SMTP.AddRecipient "", strTo$, 1
   SMTP.Subject = strSubject$
   SMTP.BodyText = strBodyText$
   x% = SMTP.Send
   If x% = 0 Then
      MsgBox "Message sent successfully."
   Else
      MsgBox "There was an error sending your message.  Error: " & CStr(x%)
   End If
   Set SMTP = Nothing
End Sub

Example usage:

SendMail "mail.yourdomain.com", "support@yourdomain.com", "jdoe@theirdomain.com", "This is the subject", "This is the body text."


Retrieve Mail Using Visual Basic and the POP3 Object

The following function can be pasted into your Visual Basic application, enabling it to display e-mail on a POP3 server.

Private Sub DisplayMail(strServer$, strAccount$, strPassword$)

   Dim cnt&, x&
   Dim Message As Object
   Dim POP3 As Object

   Set POP3 = CreateObject("EasyMail.POP3.4")
   POP3.Account = strAccount$
   POP3.Password = strPassword$
   POP3.MailServer = strServer
   POP3.DemoMode = 1

   x = POP3.Connect()
   If x <> 0 Then
      Exit Sub
   End If
   x = POP3.DownloadMessages(0)
   If x <> 0 Then
      x = POP3.Disconnect
      Exit Sub
   End If

   For Each Message In POP3.Messages
      MsgBox "SUBJECT" & vbCrLf & Message.Subject & _
               vbCrLf & vbCrLf & "MESSAGE" & vbCrLf & _
               Message.BodyText, vbOKOnly, "Message Found"
   Next Message
End Sub

Example usage:

DisplayMail "mail.yourdomain.com", "jdoe", "secret"


Retrieve Mail Using Visual Basic and the IMAP4 Object

The following function can be pasted into your Visual Basic application, enabling it to display e-mail on an IMAP4 server.

Private Sub DisplayIMAPMail(strServer$, strAccount$, strPassword$, strFolder$)

  Dim cnt&, x&
  Dim Envelope As Object
  Dim IMAP4 As Object

  Set IMAP4 = CreateObject("EasyMail.IMAP4.4")

  IMAP4.DemoMode = 1
  x& = IMAP4.Connect(strServer$)
  If x <> 0 Then
     Exit Sub
  End If

  x& = IMAP4.Login(strAccount$, strPassword$)
  If x <> 0 Then
     IMAP4.Disconnect
     Exit Sub
  End If

  x& = IMAP4.SelectMailbox(strFolder$)
  If x <> 0 Then
     IMAP4.Disconnect
     Exit Sub
  End If

  x& = IMAP4.DownloadEnvelopes(0, -1, 0)
  If x <> 0 Then
     IMAP4.Disconnect
     Exit Sub
  End If

  For Each Envelope In IMAP4.Envelopes
     MsgBox "SUBJECT:" & vbCrLf & Envelope.Subject, vbOKOnly, "Message Found"
  Next Envelope

  IMAP4.Disconnect

End Sub

Example usage:

DisplayIMAPMail "mail.yourdomain.com", "jdoe", "secret", "Inbox"


Send a Message using VC++ and the SMTP Object

Enabling your Visual C++ application to send mail is as easy as 1, 2, 3. This sample is designed to work with VC++ 5.0 or later.

Step 1

Include the #import compiler directive at the top of your cpp file like this:

/*
change to the location of emsmtp.dll
*/
#import "c:\winnt\system32\emsmtp.dll" no_namespace

Step 2

Paste the following function into your application, enabling it to send e-mail.

void SendMail(PSZ szMailServer, PSZ szFrom, PSZ szTo, PSZ szSubject, PSZ szBodyText)
{
HRESULT hr;
long nResult;

hr=OleInitialize(NULL);
if ((hr==S_OK) || (hr==S_FALSE))
{
   IEasyMailSMTPObjPtr pSMTP("EasyMail.SMTP.4");
   pSMTP->MailServer=szMailServer;
   pSMTP->FromAddr=szFrom;
   pSMTP->AddRecipient("", szTo, 1);
   pSMTP->Subject=szSubject;
   pSMTP->BodyText=szBodyText;
   nResult=pSMTP->Send();
   if (nResult!=0)
      ::MessageBox(0,
      "There was an error sending your mail.",
      "EasyMail SMTP Sample",
      MB_OK| MB_ICONWARNING);
}
if (hr==S_OK)
   OleUninitialize();

return;
}

Step 3

Call the SendMail() function.

e.g.

SendMail("mail.yourdomain.com", "fromname@yourdomain.com", "toname@theirdomain.com", "This is the subject", "This is the message body text.");


Retrieve Mail using VC++ and the POP3 Object

Enabling your Visual C++ application to retrieve mail is easy. This sample is designed to work with VC++ 5.0 or later.

Step 1

Include the #import compiler directive at the top of your cpp file like this:

/*
change to the location of empop3.dll
*/
#import "c:\winnt\system32\empop3.dll" no_namespace

Step 2

Paste the following function into your application, enabling it to retrieve e-mail.

void DispMail(PSZ szMailServer, PSZ szAccount, PSZ szPassword)
{
HRESULT hr;
long nResult=0;

hr=OleInitialize(NULL);
if ((hr==S_OK) || (hr==S_FALSE))
{
   IPOP3MainPtr pPOP3("EasyMail.POP3.4");
   pPOP3->MailServer=szMailServer;
   pPOP3->Account=szAccount;
   pPOP3->Password=szPassword;
   pPOP3->DemoMode=1;
   nResult=pPOP3->Connect();
   if (nResult==0)
   {
      pPOP3->DownloadMessages(0);
      IPOP3MessagesPtr pMessages=pPOP3->Messages;
      long nCount = pMessages->Count;
      for (int x=1; x<=nCount; x++)
      {
         IPOP3MessagePtr pMessage = pMessages->GetItem(x);
         if (pMessage)
            ::MessageBox(0, pMessage->Subject,
            "EasyMail POP3 Sample",
            MB_OK | MB_ICONINFORMATION);
      }
      pPOP3->Disconnect();
   }
   else
   {
      ::MessageBox(0,
      "There was an error retrieving your mail.",
      "EasyMail POP3 Sample",
      MB_OK | MB_ICONWARNING);
   }
}
if (hr==S_OK)
   OleUninitialize();

return;

}

Step 3

Call the DispMail() function.

e.g.

DispMail("mail.yourdomain.com",
         "jdoe", "secret");


Retrieve Mail using VC++ and the IMAP4 Object

Enabling your Visual C++ application to retrieve mail is easy. This sample is designed to work with VC++ 5.0 or later.

Step 1

Include the #import compiler directive at the top of your cpp file like this:

/*
change to the location of emimap4.dll
*/
#import "c:\winnt\system32\emimap4.dll" no_namespace

Step 2

Paste the following function into your application, enabling it to retrieve e-mail.

void DispIMAPMail(PSZ szMailServer, PSZ szAccount, PSZ szPassword, PSZ szFolder)
{
HRESULT hr;
long nResult=0;

hr=OleInitialize(NULL);

if ((hr==S_OK) || (hr==S_FALSE))
{
   IEMIMAP4Ptr pIMAP4("EasyMail.IMAP4.4");
   pIMAP4->DemoMode=1;
   nResult = pIMAP4->Connect(szMailServer);
   if (nResult!=0) return;

   nResult=pIMAP4->Login(szAccount, szPassword);
   if (nResult==0)
   {
      pIMAP4->SelectMailbox(szFolder);
      if (nResult==0)
      {
         nResult=pIMAP4->DownloadEnvelopes(0, -1, 0);
         if (nResult==0)
         {
            IEMIMAP4EnvelopesPtr pEnvelopes=pIMAP4->Envelopes;
            long nCount = pEnvelopes->Count;
            for (int x=1; x<=nCount; x++)
            {
            IEMIMAP4EnvelopePtr pEnvelope =
                  pEnvelopes->GetItem(x);

            if (pEnvelope)
               ::MessageBox(0, pEnvelope->Subject,
                            "EasyMail IMAP4 Sample",
                            MB_OK | MB_ICONINFORMATION);
            }
         }
      }
      pIMAP4->Disconnect();
   }
   else
   {
      ::MessageBox(0,
      "There was an error retrieving your mail.",
      "EasyMail IMAP4 Sample",
      MB_OK | MB_ICONWARNING);
   }
}

if (hr==S_OK)
   OleUninitialize();

return;
}

Step 3

Call the DispIMAPMail() function.

e.g.

DispIMAPMail("mail.yourdomain.com",
         "jdoe", "secret", "Inbox");


Send a Message Using Visual FoxPro and the SMTP Object

The following procudure can be pasted into your Visual FoxPro application, enabling it to send e-mail.

Procedure SendMail(strServer, strFrom, strTo, strSubject, strBodyText)

  PRIVATE x, SMTP

  SMTP = CreateObject("EasyMail.SMTP.4")
  SMTP.MailServer = strServer
  SMTP.FromAddr = strFrom
  SMTP.AddRecipient("", strTo, 1)
  SMTP.Subject = strSubject
  SMTP.BodyText = strBodyText
  x = SMTP.Send()
  If x = 0 Then
     MessageBox("Message sent successfully.")
  Else
     MessageBox("There was an error sending your message. Error: " + AllTrim(Str(x)))
  EndIf
  Release SMTP

EndProc

Example usage:

Do SendMail With "mail.yourdomain.com", "support@yourdomain.com", "jdoe@theirdomain.com", "This is the subject", "This is the body text."


Retrieve Mail Using Visual FoxPro and the POP3 Object

The following function can be pasted into your Visual FoxPro application, enabling it to display e-mail on a POP3 server.

Procedure DisplayMail(strServer, strAccount, strPassword)

  Private x, POP3

  POP3 = CreateObject("EasyMail.POP3.4")
  POP3.Account = strAccount
  POP3.Password = strPassword
  POP3.MailServer = strServer
  POP3.DemoMode = 1

  x = POP3.Connect()
  If x <> 0 Then
     return
  EndIf
  x = POP3.DownloadMessages(0)

  POP3.Disconnect
  If x <> 0 Then
     return
  EndIf

  For Each Message In POP3.Messages
     MessageBox("SUBJECT: " + Message.Subject, 0, "Message Found")
  Next Message

  Release POP3

EndProc

Example usage:

Do DisplayMail With "mail.yourdomain.com", "jdoe", "secret"


Retrieve Mail Using Visual FoxPro and the IMAP4 Object

The following function can be pasted into your Visual FoxPro application, enabling it to display e-mail on a IMAP4 server.

Procedure DisplayIMAPMail(strServer, strAccount, strPassword, strFolder)

  Private x, IMAP4

  IMAP4 = CreateObject("EasyMail.IMAP4.4")

  IMAP4.DemoMode = 1
  x = IMAP4.Connect(strServer)
  If x <> 0 Then
     return
  EndIf

  x = IMAP4.Login(strAccount, strPassword)
  If x <> 0 Then
     IMAP4.Disconnect
     return
  EndIf

  x = IMAP4.SelectMailbox(strFolder)

  If x <> 0 Then
     IMAP4.Disconnect
     return
  EndIf

  x = IMAP4.DownloadEnvelopes(0, -1, 0)
  If x <> 0 Then
     IMAP4.Disconnect
     return
  EndIf

  For Each Envelope In IMAP4.Envelopes
     MessageBox("SUBJECT: " + Envelope.Subject, 0, "Message Found")
  Next Envelope

  IMAP4.Disconnect

  Release IMAP4

EndProc

Example usage:

Do DisplayIMAPMail With "mail.yourdomain.com", "jdoe", "secret", "Inbox"


E-Mail 101 Intro

Introduction

This section is an introduction to modern e-mail technologies and related issues. Because the EasyMail Objects manage the low level e-mail details for you, It is not necessary to understand this material.

Understanding the technology, however, will enable you to build richer applications and will provide you with the know-how to use the advanced features of the EasyMail Objects.

This section consists of:

Formatting
The formatting options and MIME.

Encoding
How messages are encoded to allow binary data to pass across the Internet through text only systems.

Message Basics
The e-mail message format.

Mail Servers
Mail servers are the storage tanks for e-mail messages

SMTP
The SMTP (Simple Mail Transfer Protocol) protocol is used to send messages to a mail server.

POP3
The POP3 (Post Office Protocol Version 3) protocol is used to retrieve e-mail messages from a mail server.

IMAP4
The IMAP4 (Internet Message Access Protocol Version 4) protocol is used to retrieve e-mail messages from a mail server.


RFC

RFC (Request For Comment) Documents

The protocols and standards on the Internet are mostly governed by the plethora of RFCs floating around. EasyMail Objects supports the following RFCs:

RFC | Description
821 | The SMTP protocol
822 | Standard for the format of ARPA Internet text messages
974 | Mail routing and the domain system
1854 | SMTP Service Extension for Command Pipelining
1869 | SMTP Service Extensions (ESMTP) (Obsoletes RFC1651)
1891 | SMTP Service Extension for Delivery Status Notifications
1939 | Post Office Protocol - Version 3. (Obsoletes RFC1725)
2045 | Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. (Obsoletes RFC1521 RFC1522 RFC1590)
2046 | Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. (Obsoletes RFC1521 RFC1522 RFC1590)
2047 | MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text. (Obsoletes RFC1521 RFC1522 RFC1590)
2060 | IMAP (Internet Message Access Protocol) Version 4 rev 1. (Obsoletes RFC1730)


Format

Message Formatting

Modern e-mail messages contain a wide variety of data including images, sound files and other binary information. E-mail messages may be specially formatted by adding specific descriptions to all of the parts which make up the message.

Consider a message composed in HTML format that includes a GIF and an WAV attachment. This message has three distinct parts. It would benefit the mail reader on the receiving end if it had some way to understand the composition of each of the three parts. With this information, the mail reader could display the message in HTML, display the GIF and play the WAV file.

Standard e-mail messages do not provide this type of information, so a standard format has been created to describe message parts in a consistent manner. Any mail program which conforms to this standard will be able to describe its own messages and interpret messages created by other systems.

This standard format is known as MIME (Multipurpose Internet Mail Extensions).


MIME

Multipurpose Internet Mail Extensions

The purpose of MIME is to describe the many parts of the modern e-mail message, such as images, audio files and other attachments.

Messages encoded with MIME, may consist of many parts. MIME allows each part to be described in detail. Some parts of a MIME formatted message may even be encoded with an encoding method, like Base 64.

For example, a MIME message may include a plain text message and a GIF image. The GIF image is binary data which consists of 8 bit characters. To get the GIF image data to pass through the Internet, Base 64 could be used to encode the data into 6-bit characters. On a larger scale MIME is used to annotate the parts of the message so that the receiving mail reader will know what data is stored in the message and optionally process it. For example, instead of listing the GIF file as a generic attachment, it may display it automatically.


Message Encoding

Encoding Basics

E-mail messages may contain binary information, such as file attachments. Most of the existing Internet e-mail infrastructure, however, was not designed to handle this type of data.

In order to sneak this type of data, across the Internet, it must be converted to a format which is compatible with the computers on the Internet. This conversion process is called encoding.

One problem with binary data, is that it is often represented by 8 bit characters. Some of the computers on the Internet can not properly transfer data represented by 8 bit characters. Therefore, the process of encoding, must address converting all 8 bit characters into smaller characters which are compatible with the computers on the Internet. Once the data is sent across the Internet, it can be converted back to 8 bit characters on the receiving end.

There are several types of data encoding used today. The most popular are Base 64, UUencode and Quoted Printable.


When to Encode

Message Body

When sending a text message with no attachments it is recommended not to use any type of encoding. This allows your message to be compatible with the largest amount of e-mail clients. But if you wish to ensure that the formatting of your data is not disturbed or if your message contains characters that may be converted by or unacceptable to some mail servers you should encode the text message using either Base 64 or Quoted Printable. See the BodyEncoding property of the SMTP object to specify encoding options.

File Attachments

When sending a message with file attachments it is necessary to use some type of encoding. You must make a choice depending on the intended recipient's client software. You have two options:

  • Base 64 The preferred, default and now standard method. Not supported by some older mail clients.

  • UUencoding. "Unix to Unix" encoding. Mostly used by older systems. UUencode uses characters that are transformed by some e-mail gateways, and there are several incompatible versions of UUencode.


Base 64

Base 64 encoding is the most popular form of encoding today. This encoding method transforms 8 bit characters into 6 bit characters which are compatible with the Internet infrastructure.

Base 64 is generally used to encode binary attachments with MIME formatted messages.

The Base 64 encoding operation increases data size to 133% of its original size.


UUencode

"Unix to Unix" encoding. UUencode is an older form of encoding data. Although most modern mail systems support Base 64, most are backwards compatable with UUencode. There are still many older mail systems which only understand UUencode.

NOTE: UUencode uses characters that are transformed by some email gateways, and there are also several incompatible versions of UUencode.

UUencode transforms 8 bit characters into characters which are compatible with the Internet infrastructure.


Quoted Printable

Like Base 64 and UUencode, Quoted Printable encoding, is designed to transform 8 bit characters into characters compatible with the Internet.

Quoted Printable encoding differs in the fact that it does not convert all the characters of the message. Quoted Printable encoding only transforms characters which use more than 7 bits. Any 8 bit characters are split into two or three smaller characters.

This form of encoding is very efficient in matters where only small portions of the message data are believed to be stored in 8 bit characters. This is usually the case in message text which usually consists almost exclusively of characters less than 8 bits. It would be very inefficient to encode binary data, such as binary file attachments, with quoted printable encoding. For this reason, Quoted Printable encoding is usually only used for message body text.

If the data being encoded is mostly text, the encoded form of the data remains largely recognizable by humans.


Message Structure

E-mail messages are simply text files formatted to the specifications outlined in the various Internet e-mail RFC (Request For Comment) documents.

These RFCs detail how messages should be formatted and how systems should communicate with each other. By following these guidelines independently developed systems can communicate with each other.

An e-mail message has the following parts:

Headers

Message Data


Headers

The message headers are the first part all e-mail messages. They specify the many options of the message and also include the subject. Each line is considered a header. The collection of header lines comprises the e-mail headers.

Headers do not have to be placed in any particular order and they are mostly all optional.

NOTE: If a message is composed of many parts, such as a MIME formatted message, each part may also contain its own header. These headers will be contained in the message data section. See the section on Message Data for an example and more information.

Sample Header:

Reply-To: "Quiksoft Support" <support@quiksoft.com>
From: "John Alessi" <jalessi@quiksoft.com>
To: "Bill Volz" <wvolz@quiksoft.com>
CC: "Pat Brady" <pbrady@quiksoft.com>
Subject: Please send product information.
Date: Thu, 4 Jun 1998 16:00:04 -0400
MIME-Version: 1.0
Content-Type: text/plain; charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
X-Priority: 3
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook Express 4.72.3110.5
X-MimeOLE: Produced By Microsoft MimeOLE V4.72.3110.3

Reply-To

If this header is specified, the sender wishes all replies to this message to go to the reply-to address instead of the from address.

From

Although the from address is stated in the headers, it is important to note that this may actually be different than that address which actually sent the message.

To

Who the message was sent to.

CC

Who the message was carbon copied to.

Subject

The message subject.

Date

The date and time of message creation is specified by the "Date:" header. It also contains a reference to the time zone used to calculate the date and time. In this example the message was created in a time zone four hours less than GMT.

MIME-Version

If the message was encoded with MIME, this value represents the version used.

Content-Type

The content-type header is used to declare the general type of data, while the subtype specifies a specific format for that type of data. Thus, a content-type of "text/plain" tells the user agent that the data is text, in a plain format. The optional charset parameter informs the mail reader that the message was intended to be displayed with the "iso-8859-1" character set. This header is only used with MIME messages.

Content-Transfer-Encoding

Used to specify an auxiliary encoding that was applied to the data in order to allow it to pass through mail transport mechanisms which may have data or character set limitations. This header is only used with MIME messages.

Custom Headers (X-* Type)

The headers beginning with "X-" are custom headers which were added by the program which created the message. These headers may be interpreted by a mail reader which is aware of them. In this way, custom headers can specify that the message contains information in a special format, which the mail reader can take advantage of if it knows how. If a custom header is not recognized by the mail reader, it is simply ignored.

A popular custom header is the "X-Priority" header. The value of this property is read from the message header "X-Priority". Different mail readers may set or interpret the X-Priority setting differently. Some may not set or interpret it at all. The popular readers set or interpret "4"=low, "3"=normal and "1"=high.


Message Data

Immediately following the message headers, is the message data. The message data is composed of the body text and any file attachment information.

This is a very simple message with no file attachments.

Please send EasyMail product information to bill@domain.com.
Thanks.
--
John Alessi
Quiksoft Corporation
http://www.quiksoft.com

.

NOTE: The trailing period indicates the end of the message.

This is a message with one GIF file attachment. The message is encoded with MIME, the message body is encoded with Quoted Printable and the GIF is encoded with Base 64.

This is a multi-part message in MIME format.

------=_NextPart_000_0051_01BD9B7E.F01FEA90
Content-Type: text/plain;charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Message text.

--
John Alessi
Quiksoft Corporation
http://www.quiksoft.com

------=_NextPart_000_0051_01BD9B7E.F01FEA90
Content-Type: image/gif;name="bullet.gif"
Content-Transfer-Encoding: base64
Content-Disposition: attachment;filename="bullet.gif"

R0lGODlhAwALAJEAAP////8AANUaGgAAACH5BAEAAAAALAAAAAADAAsAAAIJhH9hoeygkAQFADs=

------=_NextPart_000_0051_01BD9B7E.F01FEA90--

.

Note that the attachment in the preceding example is preceded by an attachment header.

Content-Type: image/gif;name="bullet.gif"
Content-Transfer-Encoding: base64
Content-Disposition: attachment;filename="bullet.gif"

An attachment header precedes all attachments and is used to describe the various properties of the attachment.


E-Mail Servers

E-mail servers are the storage warehouse for e-mail messages. Not only do they store the messages, but they also know how to receive new messages and how to distribute stored ones.

Modern e-mail servers may use a variety of protocols to communicate with the Internet, however the most common protocols used are SMTP, POP3 and IMAP4.

SMTP (Simple Mail Transport Protocol)
Used for sending and receiving messages

POP3 (Post Office Protocol Version 3)
Used for delivering messages to mail readers

IMAP4 (Internet Message Access Protocol Version 4)
Used for delivering messages to mail readers

Mail readers are at the opposite end of the server. Since mail servers receive messages via SMTP, e-mail readers must send e-mail to a mail server using SMTP. Likewise, since mail servers send messages using POP3 and optionally IMAP4, mail readers must receive messages from mail servers by using the POP3 or IMAP4 protocol.


SMTP Protocol

Simple Mail Transport Protocol

SMTP is a protocol governing electronic mail transmission and reception.

The Conversation

A conversation is established with a SMTP server by connecting to port 25 on the SMTP server. After the initial connection, the client sends a HELO command followed by a domain name. This tells the SMTP server to whom it is talking to. The SMTP server may decide to terminate the connection at that point if it does not wish to speak to the specified domain.

If the HELO command is accepted by the remote server, the SMTP client issues a MAIL-FROM command followed by the "from address" of the e-mail being sent. Once again, the SMTP server may decide to terminate the connection if it does not wish to receive mail from the specified sender.

NOTE: Some SMTP servers may do a reverse lookup on the domain name specified for the HELO or FROM command. If the IP address of the SMTP client is not registered to that domain, the client may be considered an imposter, and the connection will be dropped.

After the from address is accepted, the SMTP client issues a RCPT-TO command followed by the address of the intended recipient. At this point the SMTP server has the opportunity to reject mail being sent to the specified address. For example, some SMTP servers will only accept mail for local users.

The SMTP client may issue multiple RCPT-TO commands to the server, thus adding more recipients to the message. When the SMTP client is through adding the recipients to the message, it issues the DATA command to the server.

If the DATA command is accepted, the SMTP client then proceeds to send the message headers, followed by a blank line, followed by the message body and file attachment data. When the SMTP client is through sending the message data, it sends a carriage return, followed by a period, followed by a carriage return, to indicate the end of the message.

At this point the SMTP server acknowledges the receipt of the message data. The SMTP client may then proceed to send another message, or can send the QUIT command to terminate the conversation.

NOTE: It is important to point out that the from address specified in the MAIL-FROM command does not have to be the same address which is put in the "From:" header. Likewise, the SMTP client may send mail to someone with a RCPT-TO command but not put that recipients address in the "To:" or "CC:" header. This is exactly how a blind carbon copy is sent.

See Also

Extended SMTP (ESMTP)


Extended SMTP (ESMTP)

Extended SMTP consists of several extensions to the basic SMTP protocol. All of the extensions are optional. An SMTP server may support any extension that it chooses, or none at all.

The EasyMail SMTP object supports the following extensions:

Pipelining

A normal SMTP conversation involves several fragments of data being sent from the client to the server. After each fragment is sent, the client waits for the server to send back an acknowledgement. Once the acknowledgement is received, the client sends the next fragment, and so on...

This process is very time consuming because many parts of the Internet make use of high latency network links. The client spends a lot of its time waiting for the server to send back a response. To combat this situation, pipelining may be used.

Pipelining allows the client to batch several fragments of data together and send them all at once. The server then sends back one acknowledgement for the combined set of data. Since the fragments and acknowledgements are combined, the client spends less time waiting for the server to respond and can therefore send the message faster.

The EasyMail SMTP object supports pipelining. It is controlled with the ESMTP_Pipelining property.

Delivery Status Notifications (DSN)

Standard SMTP servers normally support delivery status notifications (DSN). The DSN extensions allow greater control of the notification process.

Specifically, the DSN extensions allow you to specify when and how notifications are sent.

The EasyMail SMTP object supports DSN. To control how and when notifications are sent, see the ESMTP_DSN_Notify and ESMTP_DSN_Return properties.

The DSN extensions also allow for an "Envelope ID" to be included in an outbound message. The ID is returned as a MIME part of all delivery status notifications pertaining to the message. This facility allows client applications to match delivery status notifications to the original message.

To specify a DSN Envelope ID for a message, set the ESMTP_DSN_ID property.

Here is an example MIME part to a DSN message. Note that the Envelope ID is specified as "4565875".

--RAA00962.916092539/Muse.domain.com
Content-Type: message/delivery-status

Original-Envelope-Id: 4565875
Reporting-MTA: dns; Muse.domain.com
Received-From-MTA: DNS; clavin.domain.com
Arrival-Date: Mon, 11 Jan 1999 17:08:57 -0500 (EST)

Original-Recipient: rfc822;jdoe@domain.com
Final-Recipient: RFC822; wxv0001@Muse.domain.com
Action: delivered (to mailbox)
Status: 2.1.5
Last-Attempt-Date: Mon, 11 Jan 1999 17:08:59 -0500 (EST)

--RAA00962.916092539/Muse.domain.com

See Also

SMTP Protocol


POP3 Protocol

Post Office Protocol Version 3

POP3 is the most recent version of a standard client-server protocol for receiving e-mail.

The Conversation

POP3 mail servers listen for mail requests and forward mail to the requesting party. The default port on which the POP3 server listens for these requests is 110.

Client side mail readers can issue a predefined set of commands to the mail server, to access the mail in their own desired fashion.

By default, POP3 clients login to the POP3 server by sending the password for the mail account as clear text. This may be undesirable in high security-type situations. With POP3's optional APOP authentication, the password itself is never sent to the remote mail server. Instead, a digest is created using the RSA MD5 algorithm. This digest is based on the password and a unique value supplied by the POP3 mail server during the connection. This digest is sent to the mail server in lieu of the password. Because the unique value supplied by the mail server changes with each connection, APOP authentication ensures that a different digest will be sent each time you log onto the sever. This seriously reduces the ability for a network sniffing program to capture your password.

Sessions

A POP3 session is created when a remote user connects to a mailbox on the POP3 mail server. The session ends when the remote user disconnects from the POP3 mail server. While a session is open, no other user can retrieve mail from the POP3 mailbox, however mail can still be sent to that account. This is by design of the POP3 protocol.

While in a session, regardless of new mail which may be arriving in the mailbox, all things remain equal. At the time the session is initiated, mailbox state is saved and the entire session operates off of that cached state. Once a session is terminated, values obtained from that session may no longer be valid.

For example, if you initiate a session with a POP3 mail server and find that there are five messages available. While in the session, operations on these messages require a message number, which is the position of the message in the list of five. Once you terminate your session, you can not assume that five messages are still available. If you initiate another session, you can not assume that the message number three from the first session is message number three in the new session.

Because of this, certain message operations are only valid while in the same session which downloaded the message. Once a session is terminated, if you wish to perform server operations on a specific message, you will need to establish a new session, locate the message by comparing its properties (subject, date, message id, etc...) to ones you saved from the previous session, and then act upon the message before terminating the new session.


IMAP4 Protocol

Internet Message Access Protocol Version 4

The IMAP4 protocol is an alternative to POP3 for retrieving e-mail, however IMAP4 is a newer protocol and is not supported by all mail servers. The default port on which the IMAP4 server operates is 143.

The IMAP4 protocol was designed to allow messages to be managed on the server. Since the messages remain on the server, IMAP4 is a great protocol for users who access e-mail from different client computers.

IMAP4 also allows users to share mailboxes which makes IMAP4 attractable to users who share the management of specific e-mail accounts.

Users

IMAP4 servers identify users by an account name and a password. Users may be given specific access to different resources.

Mailboxes / Folders

An IMAP4 server stores messages in different mailboxes. Sometimes an IMAP4 mailbox is referred to as a folder. The terms may be used interchangeably.

More than one user may be given access to an IMAP4 mailbox, thus allowing mailboxes to be shared by multiple users.

Inbox

Each user has a special "Inbox" folder where incoming messages are stored.

Subscriptions

Each user may subscribe to different folders on the IMAP4 server. Subscribing to a folder indicates that the folder has some greater level of importance. Although you can download mail from any mailbox for which you have access, most client e-mail applications handle subscribed folders differently. For example, some clients only check subscribed folders when automatically scanning for new mail, .

Identifying Messages

IMAP4 messages may be referred to by either their ordinal position within a mailbox, or their unique id. All messages stored on an IMAP4 server have a unique id. From session to session, a messages ordinal position may change, however its unique id will always remain the same. This is to facilitate identifying messages from session to session.

Session States

The IMAP4 session consists of three different states: connected, authenticated and selected.

Connected State

An IMAP4 session is in the connected state while the client is connected to the server but not logged in as a user at this time. This is generally the case just prior to the user login, or just after a user logout.

Authenticated State

The IMAP4 session is in the authenticated state when the client is connected to the server and a user is logged in, however no mailbox has been selected. This is generally the case just after login and prior to selecting a mailbox.

Selected State

The selected state indicates that a client has connected to the server, logged in and selected a mailbox.


SMTP Usage

ProgID | EasyMail.SMTP.4
CLSID | AA6D8BF2-99BE-11d2-B3C3-00A0CC3A50B9

The EasyMail SMTP object is a lightweight COM object which which generates Internet e-mail. It can be used for server side processing in ASP files, and Perl scripts. It can also be used in any other COM compatible app. ie: C++, Internet Explorer, VB, Delphi, etc...

The registry application name for the this object is "EasyMail.SMTP.4"

In order to keep the EasyMail object efficient, it does not carry a lot of the general ActiveX control overhead. In any event, the EasyMail SMTP object can be used and programmed just as easy as any ActiveX control.

VB / VB Script Usage:

set SMTP = CreateObject("EasyMail.SMTP.4")
SMTP.MailServer="mail.yourdomain.com"
... set other properties
result = SMTP.Send()

Usage in other application development systems:

In order to use the object, you will have to create it in your code. EasyMail is used like an OLE Automation server or COM object. Although the method for creating an COM object is different within each development system, they all support it.

In VB the command to create an object is "CreateObject()" and is used like such:

Set SMTP = CreateObject(EasyMail.SMTP.4")

After the object is created, you can access all of its properties and methods as usual:

SMTP.Message = "This is the mail message."
... set other properties ...
Result = SMTP.Send()

The samples section of this documentation contains sample code snippets for various development systems.


AutoWrap Property (SMTP)

AutoWrap Property

SMTP Object

Sets the maximum line length of the outgoing message.

Type: Long

Remarks

Setting this properties value to any value greater than 0 turns on the AutoWrap feature and the message body text will be word wrapped so that no line contains more than the number of characters specified.

Some Internet mail servers have trouble processing messages with lines longer than 76 characters. Unless you are sure that your message will only be processed by mail servers which can handle messages with longer line lengths, do not set this property to a value greater than 76.

The default and recommended setting is 76.

See Also

GetWrappedBodyText() Method


BodyEncoding Property (SMTP)

BodyEncoding Property

SMTP Object

Sets the message body text encoding options for a MIME formatted message

Type: Long

This property may be set to one one of the following values.

Value | Meaning
0 | Do not encode message body text (default)
1 | Enclode message body text using Quoted Printable
2 | Encode message body text using Base 64

Remarks

This property has no effect if the Encoding property is not set to 0.

See Also

Encoding Property
BodyText Property
Message Headers


BodyFormat Property (SMTP)

BodyFormat Property

SMTP Object

Sets the message body text format options for a MIME formatted message.

Type: Long

This property may be set to one of the following values:

Value | Meaning
0 | Plain Text (default)
1 | HTML
2 | RTF

Remarks

This property sets the format of the message body. It may be used by the recipients mail reader to interpret the message body format.

You can include HTML tags in your message body if you set this property to 1. Different mail readers may not interpret message body text sent as HTML and therefore will display the tags instead of processing them. Some mail readers interpret some of the HTML and not the rest. If you are going to send as HTML format, it is suggested that you only use basic character formatting commands to ensure compatibility with different mail readers.

This property has no effect if the Encoding property is not set to 0.

If the object is running in demo mode, this property will have no effect.


BodyText Property (SMTP)

BodyText Property

SMTP Object

Sets the message body text.

Type: String

Remarks

This property specifies the main body text of the mail message.

The text should be formatted according to the setting of the BodyFormat property.

To facilitate adding complicated or large amounts of text to the message, you may use the ImportBodyText() method, which will fill the BodyText property with data from a system file.

See Also

BodyFormat Property
BodyEncoding Property
ImportBodyText() Method


CharSet Property (SMTP)

CharSet Property

SMTP Object

Specifies the character set to be specified in the message header.

Type: String

Remarks

The name of the character set used to compose the message. Any character set may be specified. e.g. US-ASCII, ISO-8859-*, ISO-2022-JP. Defaults to US-ASCII.

See Also

Message Headers


Domain Property (SMTP)

Domain Property

SMTP Object

The domain property may optionally be set to your e-mail domain name. e.g. "aol.com".

Type: String

Remarks

If this property is not specified the domain is obtained from the from address property. e.g. If from address is sales@quiksoft.com the domain would be set to "quiksoft.com" .

This property is used in the HELO command to initiate a conversation with a SMTP mail server.

See Also

SMTP Protocol


Encoding Property (SMTP)

Encoding Property

SMTP Object

Sets the message format and encoding scheme.

Type: Long

This property may be set to one of the following properties.

Value | Meaning
0 | Use MIME format for the message and Base 64 encoding for file attachments (default)
1 | Use plain format for the message and UUencoding for file attachments.

See Also

Message Headers
BodyEncoding Property


ESMTP_DSN_ID Property (SMTP)

ESMTP_DSN_ID Property

SMTP Object

Specifies the ESMTP delivery status notification envelope ID for this message.

Type: String

Remarks

The delivery status notification envelope ID specified for a message, is returned with any delivery status notifications for that message. The ID may be used to programatically match messages sent, with delivery status notifications received.

The setting of this property applies to all recipients of the message.

If ESMTP delivery status notifications are not supported by the server, the value of this property is ignored.

See Also

ESMTP
ESMTP_DSN_Notify Property
ESMTP_DSN_Return Property


ESMTP_DSN_Notify Property (SMTP)

ESMTP_DSN_Notify Property

SMTP Object

Controls what events trigger ESMTP delivery status notifications.

Type: Long

The following values are valid:

Value | Meaning
0 | Server's default
1 | Notify on failure
2 | Notify on success
4 | Notify on delay
8 | Notify never

Remarks

Values 1, 2 and 4 may be combined to customize the notification rules.

The setting of this property applies to all recipients of the message.

If ESMTP delivery status notifications are not supported by the server, the value of this property is ignored.

See Also

ESMTP
ESMTP_DSN_Return Property
ESMTP_DSN_ID Property
ReturnReceiptTo Property


ESMTP_DSN_Return Property (SMTP)

ESMTP_DSN_Return Property

SMTP Object

Controls how much of the original message is returned with ESMTP delivery status notifications.

Type: Long

The following values are valid:

Value | Meaning
0 | Server's default
1 | Return header
2 | Return full message

Remarks

The setting of this property applies to all recipients of the message.

If ESMTP delivery status notifications are not supported by the server, the value of this property is ignored.

See Also

ESMTP
ESMTP_DSN_Notify Property
ESMTP_DSN_ID Property
ReturnReceiptTo Property


ESMTP_Pipelining Property (SMTP)

ESMTP_Pipelining Property

SMTP Object

Toggles ESMTP pipelining.

Type: Long

This property may be set to one of the following values.

Value | Meaning
0 | Disable pipelining
1 | Enable pipelining

Remarks

Pipelining is an ESMTP method which allows messages to be sent faster than with the regulations imposed by the basic SMTP protocol.

If ESMTP pipelining is not supported by the server, basic SMTP will be used regardless of the setting of this property.

See Also

ESMTP


EventLogging Property (SMTP, POP3 Main, IMAP4 Main)

EventLogging Property

SMTP Object, POP3 Main Object, IMAP4 Main Object

Enables or disables Windows NT event logging.

Type: Long

This property may be set to one of the following values:

Value | Meaning
0 | Disables event logging (default)
1 | Enables event logging

Remarks

When event logging is enabled, critical events are added to the Windows NT event log.

This property will have no effect on non Windows NT systems.

See Also

LogFile Property
ConnectLog() Event


From Property (SMTP)

From Property

SMTP Object

Sets the display name of the e-mail sender.

This property is used for display-only purposes on the receivers system when indicating who the mail is from.

i.e. John Doe

Type: String

Remarks

This property is not required to send mail. If this property is not specified, the receivers mail reader will use the senders e-mail address instead of this friendly display name.

Use this property if you wish your e-mail to be displayed with a friendly sender name.

See Also

FromAddr Property
OptionFlags Property
Message Headers


FromAddr Property (SMTP)

FromAddr Property

SMTP Object

Sets the from address of a message.

This property is used to specify who the mail is from. It must be specified as a valid Internet e-mail address.

i.e. jdoe@domain.com

Type: String

Remarks

The value specified by this property is used with the SMTP "MAIL FROM" command during the SMTP conversation. This command indicates to the SMTP host, the e-mail address of the message sender. Most mail servers will accept mail from anyone, however some mail servers will only accept mail from some senders.

This property is required to send mail.

See Also

From Property
OptionFlags Property
SMTP Protocol


License Key Property (SMTP)

LicenseKey Property

SMTP Object

The license key to be used with the object.

Type: String

Remarks

This property holds the license key for the object. If the LicenseKey property is not assigned a valid license key, the object will operate in demo mode.

While in demo mode, the object will include a small prefix to your messages and will only send message body text in plain text format.

To take the object out of demo mode, you must assign it a valid license key. License keys can be obtained from Quiksoft Corporation.

See Also

Licensing


LogFile Property (SMTP, POP3 Main, IMAP4 Main)

LogFile Property

SMTP Object, POP3 Main Object, IMAP4 Main Object

Path and file name of log file to output all transactions with the server.

Type: String

Remarks

Path to log file must already exist. The file will be created if it does not already exist, otherwise it will be appended to. If the object is running in a security context, it must have create and write access in the path specified.

See Also

EventLogging Property
ConnectLog Event


MailPort Property (SMTP, POP3 Main, IMAP4 Main)

MailPort Property

SMTP Object, POP3 Main Object, IMAP4 Main Object

Specifies the port on which to communicate with the remote server.

Type: Long

Remarks

The object defaults are as follows:

Object | Default Setting
SMTP | 25
POP3 | 110
IMAP4 | 143

See Also

MailServer Property (POP3 Mail Object, IMAP4 Main Object)
MailServer Property (SMTP Object)
Firewalls


MailServer Property (SMTP)

MailServer Property

SMTP Object

Sets the mail server and optional backup servers through which all mail should be sent.

Type: String

Remarks

To improve efficiency, the SMTP object does not send mail directly to the recipients mail server. Instead, it sends mail to another SMTP server which then forwards the mail to the recipients server. This removes overhead from the SMTP object and allows it to work much faster.

Set this property to the name of your mail server. e.g. "mail.domain.com". If you wish to allow the control to try multiple mail server in case of failures you can delimit them by using a semicolon.

e.g. mail.aol.com;mail.quiksoft.com;mail.earthlink.net

For best performance, it is recommended that the specified mail server(s) is(are) on the same local network as the SMTP object.

If you are going to use the Save() method or the SubmitToExpress() method to submit the e-mail to SMTP Express, this property is ignored.

This property is required before any calls to the Send() method.

See Also

MailPort Property
Save() Method
SubmitToExpress() Method
Send() Method


OptionFlags Property (SMTP)

OptionFlags Property

SMTP Object

Sets various options.

Type: Long

This property may be set to any combination of the following values:

Value | Meaning
1 | Message will not include a "From:" header.
2 | Message will not include a "Date:" header.

See Also

Message Headers


PerformanceMode Property (SMTP)

PerformanceMode Property

SMTP Object

Sets performance options.

Type: Long

This property may be set to any combination of the following values:

Value | Meaning
1 | Send messages on a second thread. Selecting this option causes the Send() method to create a worker thread for sending the message, and use your applications main thread to process Windows messages until the transmission is complete. This architecture allows your your application to be responsive while the transmission is in progress, but prevents the method from returning until the transmission is complete. During the transmission the worker thread will be manipulating the object and assumes that the object will not be manipulated by any other process during this time. Accessing the object while a transmission is in progress can lead to unpredictable results and is not recommended. The only exception to this rule is the Cancel() method, which may be called during the transmission, to abort the process.


Priority Property (SMTP)

Priority Property

SMTP Object

Sets the priority of the message.

Type: String

Remarks

The value of this property is placed in a message header as an "X-Priority" value. Different mail readers may interpret the X-Priority setting differently. Some may not interpret it at all. The popular readers interpret "4"=low, "3"=normal and "1"=high.

See Also

Message Headers


ReplyTo Property (SMTP)

ReplyTo Property

SMTP Object

Sets the address for which replies to this message should be sent.

Type: String

Remarks

Normally, replies to an e-mail message are sent to the original sender of the message. In some cases, it may be desirable to have replies sent a different address.

Setting the ReplyTo property to an e-mail address, will cause all replies to that message to go to the reply-to address instead of the original sender.

See Also

From Property
FromAddr Property
ReturnReceiptTo Property
Message Headers


ReturnReceiptTo Property (SMTP)

ReturnReceiptTo Property

SMTP Object

Specifies an e-mail address to send receipts to.

Type: String

Remarks

Specifying an e-mail address for this property adds a "Return-Receipt-To" message header.

This header is intended for mail clients not servers. If the receiving mail client software supports this header, it may send a receipt to the address specified when the message is received.

See Also

From Property
FromAddr Property
ReplyTo Property
ESMTP_DSN_Notify Property
ESMTP_DSN_Return Property
Message Headers


Subject Property (SMTP)

Subject Property

SMTP Object

The subject of the message.

Type: String

See Also

BodyText Property
Message Headers


Tag Property

All Objects

The tag property is not processed by the object and may be used for user defined purposes.

Type: String


TimeOut Property (SMTP, POP3 Main, IMAP4 Main)

TimeOut Property

SMTP Object, POP3 Main Object, IMAP4 Main Object

Specifies the timeout value in seconds.

Type: Long

Remarks

This property specifies the maximum amount of time that the object will wait for a response from the server before returning an error. The default setting is 30 seconds.


Version Property

SMTP Object, POP3 Main Object, IMAP4 Main Object, MessagePrinter Object

Returns the version of the object.

Type: String

Remarks

This property is read-only.


AddAttachment Method (SMTP)

AddAttachment Method

SMTP Object

Adds a file attachment to the current e-mail message.

void AddAttachment(string strPath, long nOptions)

Parameters

string strPath

Specifies the file which you wish to attach to the message.

long nOptions

Specifies the options to use when attaching the file. May be one of the following values:

Value | Meaning
0 | No options selected (default)
1 | Uses generic content-type

Return Values

Zero if successful, non zero if the operation failed.

If the AddAttachment() method fails, it will return one of the following error codes.

Value | Meaning
1 | Failure opening file
2 | Failure reading file.

Remarks

This method can be called multiple times to add a virtually unlimited number of attachments to your message.

Attachments are encoded with the format specified in the Encoding property.

When a file is attached to a message, it is distinguished by a content type. The content type describes what type of data the file holds. For example, "image/gif" is the content type for a GIF image file. Some mail readers will use this information and apply special processing to files with popular content types. For example, the mail reader may automatically display a GIF image, or play an audio track.

By default the content type is automatically read from the registry on the computer which creates the message, however you may disable this feature if you wish to prevent mail readers from potentially processing the file information instead of just listing it as an attachment.

By setting the option parameter of the AddAttachment() method to 1 (use generic content-type), you force the system to use a generic content type for attachments instead of using the associated type from the registry. The generic content type which the object uses is "application/octet-stream."

When a generic content type is used, the receiving system can not do any further processing of the information because it can not determine what the information actually is.

See Also

AddAttachmentEx() Method
Encoding Property


AddAttachmentEx Method (SMTP)

AddAttachmentEx Method

SMTP Object

Adds a file attachment to the current e-mail message.

long AddAttachmentEx(string strFile, string strHeaders, long nOptions)

Parameters

string strFile

Specifies the filename of the attachment to add.

string strHeaders

Specifies additional headers to be added to the attachment's MIME part header.

long nOptions

Specifies the options to use when attaching the file. May be one of the following values:

Value | Meaning
0 | No options selected (default)
1 | Do not automatically add "Content-Type:" header
2 | Do not automatically add "Content-Transfer-Encoding:" header
4 | Do not automatically add "Content-Disposition:" header
8 | Do not automatically add "Content-Discription:" header
256 | Group attachment with body text, useful for adding images to HTML messages

Return Values

Zero if successful, non zero if the operation failed.

If the AddAttachmentEx() method fails, it will return one of the following error codes.

Value | Meaning
1 | Failure opening file
2 | Failure reading file
3 | Invalid parameter

Remarks

This method can be called multiple times to add a virtually unlimited number of attachments to your message.

Attachments are encoded with the format specified in the Encoding property. Headers of UUencoded messages can not be grouped, appended to or removed.

Custom headers are not validated by this method.

See Also

AddAttachment() Method
Encoding Property


AddCustomHeader Method (SMTP)

AddCustomHeader Method

SMTP Object

Adds a custom message header to the current e-mail message.

void AddCustomHeader(string strName, string strValue)

Parameters

string strName

Specifies the name of the custom message header.

string strValue

Specifies the data to be included in the message header.

Remarks

Although it is not necessary, to conform with standard custom message header information, you may want to prepend the header name with an "X-".

e.g.

AddCustomHeader("X-Organization", "Quiksoft Corporation")

would cause

X-Organization: Quiksoft Corporation

to be added to the headers of the message.

This method may be called repeatedly to add a virtually unlimited number of custom message headers to the message. The specified header will be appended to message headers, even if it already exists.

See Also

Message Headers


AddRecipient Method (SMTP)

AddRecipient Method

SMTP Object

Adds a normal, carbon copy or blind carbon copy recipient to the message.

void AddRecipient(string strName, string strAddress, long nType)

Parameters

string strName

The friendly name of the recipient e.g. "John Doe".

string strAddress

The e-mail address of the recipient e.g. "jdoe@aol.com".

long nType

May be any one of the following values:

Value | Meaning
1 | Normal recipient
2 | Carbon copy recipient
3 | Blind carbon copy recipient

Remarks

This method can be called multiple times to add virtually an unlimited number of recipients to your message.

See Also

Clear() Method
Message Headers


Cancel Method (SMTP)

SMTP Object

Cancels the transmission of the message currently being sent.

void Cancel()

Parameters

None

Remarks

If a transmission is cancelled, the Send() method which initiated the transmission will return a special error code. See the Send() method for more information.

See Also

Send() Method


Clear Method (SMTP)

Clear Method

SMTP Object

Clears specified values previously set in the object.

void Clear(long nType)

Parameters

long nType

May be any one of the following values:

Value | Meaning
1 | Clear all recipients
2 | Clear all attachments
4 | Clear all custom message headers

See Also

Reset() Method


DoSendDlg Method (SMTP)

DoSendDlg Method

SMTP Object

Displays a message composition dialog box. The dialog is loaded with the data currently stored in the object.

long DoSendDlg(long hWnd, string strCaption, long nOptions)

Parameters

long hWnd

A handle to the window which should be used as the parent of the dialog. Passing a value of zero will cause the Desktop window to be used.

string strCaption

The caption to be displayed at the top of the dialog.

long nOptions

May be zero or any combination of the following values:

Value | Meaning
2 | Read-only
4 | Suppress attachments
32 | Show "send" message options
64 | Show "save" message options

Return Values

Return values less than 64 indicate that the operation completed successfully.

Value | Meaning
1 | Operation completed normally. User chose to cancel.
10 | Operation completed normally. User chose send.
15 | Operation completed normally. User chose save.
100 | Invalid parameter.
126 | Dialog module not found
127 | Dialog module procedure not found. The dialog module may be corrupted.
1400 | An invalid window handle was specified in the hWnd parameter.

Remarks

The DoSendDlg() method displays a message composition dialog loaded with the data currently stored in the object.

If the user edits the message and then chooses to send the message, the data in the object will be updated to reflect the changes before the method returns. If the user chooses to cancel by closing the dialog box without sending, the data in the object will remain as it was before the method call.

See Also

DoViewDlg() Method (POP3 Message , IMAP4 Message)


GetWrapedBodyText Method (SMTP)

GetWrapedBodyText Method

SMTP Object

Returns the body text of the message formatted as it will be word wrapped in the message.

string GetWrappedBodyText()

Parameters

None

Remarks

This method is useful for previewing how your message will look after any automatic word wrapping is applied. Automatic word wrapping is only enabled If the AutoWrap property is set to a value greater than zero. If the AutoWrap property is set to zero, this method will return the body text without any word wrapping.

See Also

AutoWrap Property


ImportBodyText Method (SMTP)

ImportBodyText Method

SMTP Object

Imports text from a system file into the message body.

long ImportBodyText(string strPath)

Parameters

string strPath

Specifies the system file which contains the text to import into the message body.

Return Values

Zero if successful, non zero if the operation failed.

Error Codes:

If the ImportBodyText() method fails, it will return one of the following error codes.

Value | Meaning
1 | Failure opening file
2 | Failure reading file

Remarks

Calling this method, will overwrite any existing message body text. If this method is successful, the imported text will be available via the BodyText property.

See Also

BodyText Property


LoadMessageFromHandle Method (SMTP)

LoadMessageFromHandle Method

SMTP Object

Loads the object with message data referenced by a message handle.

long LoadMessageFromHandle(long hMsg)

Parameters

long hMsg

A handle to a message.

Return Values

Zero if successful, non zero if the operation failed.

Value | Meaning
100 | Invalid parameter
101 | A fatal exception was encountered.

Remarks

Before the message is loaded, any existing attachments and recipients are deleted from the object. The following properties are also reset:

BodyText, Subject, From, FromAddr, ReturnReceiptTo, ReplyTo, CharSet, ESMTP_DSN_ID, ESMTP_DSN_Notify and Priority.

See Also

CreateMessageHandle (POP3 Message, IMAP4 Message)


Reset Method (SMTP)

Reset Method

SMTP Object

Resets all properties to their default values and removes all recipients, attachments and custom message headers.

void Reset()

Parameters

None

See Also

Clear() Method


Save Method (SMTP)

Save Method

SMTP Object

The Save method creates an e-mail file from the object's settings.

long Save(szFileName)

Parameters

string szFileName

The name of the output file.

Return Values

Zero if successful, non zero if the operation failed.

Error Codes:

If the Save() method fails, it will return one of the following error codes.

Value | Meaning
3 | Out of memory
10 | Error opening file
11 | Error reading from file
12 | Error writing to file

Remarks

This method quickly creates an e-mail file based on the properties of the object. The e-mail file is formatted to standard specifications (RFC 822) and should be understood by other mail programs.

See Also

Send() Method
SubmitToExpress() Method


Send Method (SMTP)

Send Method

SMTP Object

The Send method initiates a conversation with an SMTP mail server, sends the message and closes the conversation.

long Send()

Parameters

None

Return Values

Zero if successful, non zero if the operation failed.

Error Codes:

If the Send() method fails, it will return one of the following error codes.

Value | Meaning
1 | An unknown error has occurred
2 | An error has resulted because there was no message specified
3 | The process has run out of memory.
4 | An error has occurred due to a problem with the message body or attachments.
5 | There was a problem initiating the conversation with the mail server. Ensure the setting of the Domain property is correct.
6 | There was an error terminating the conversation with the SMTP mail server.
7 | The from address was not formatted correctly or was rejected by the SMTP mail server. Some SMTP mail servers will only accept mail from particular addresses or domains. SMTP mail servers may also reject a from address if the server can not successfully do a reverse lookup on the from address.
8 | An error was reported in response to a recipient address. The SMTP server may refuse to handle mail for unknown recipients.
9 | There was an error connecting to the SMTP mail server.
10 | There was an error opening a file. If you have specified file attachments, ensure that they exist and the you have access to them.
11 | There was an error reading a file. If you have specified file attachments, ensure that they exist and the you have access to them.
12 | There was an error writing to a file. Ensure that you have sufficient disk space.
15 | No mail server specified.
16 | Could not create socket.
17 | Could not resolve host.
18 | Connected but server sent back bad response.
19 | Could not create thread.
20 | Cancelled as a result of calling the Cancel() method.

Remarks

If you can not determine the problem based on the Send() error code, you should either turn on logging by using the LogFile property, or monitor the ConnectLog() event.

The progress of the transmission can be monitored by the Progress() event. The transmission may be cancelled by calling the Cancel() method.

See Also

Cancel() Method
Progress() Event
Save() Method
SubmitToExpress() Method


SubmitToExpress Method (SMTP)

SubmitToExpress Method

SMTP Object

The SubmitToExpress method submits the current message to EasyMail SMTP Express for delivery.

long SubmitToExpress(string strPath)

Parameters

string strPath

The path to the Easymail SMTP Express directory on the computer where EasyMail SMTP Express is installed.

Return Values

Zero if successful, non zero if the operation failed.

Error Codes:

If the SubmitToExpress() method fails, it will return one of the following error codes.

Value | Meaning
1 | Invalid path to EasyMail SMTP Express installation, or invalid access rights in that path.

Remarks

If the SubmitToExpress() method succeeds, Easymail SMTP Express will queue and deliver the message in the background. If the method fails, you may call the Send() method as a backup.

See Also

Send() Method


ConnectLog Event (SMTP)

ConnectLog Event

SMTP Object

Echoes SMTP transactions as they are processed. Useful for debugging or logging purposes.

ConnectLog(string strText, long nReserved)

Parameters

string strText

A textual indication of the event

long nReserved

Reserved for future use

See Also

LogFile Property
EventLogging Property


Progress Event (SMTP)

Progress Event

SMTP Object

Indicates the status of a message transmission.

Progress(long nComplete, long nTotal)

Parameters

long nComplete

The approximate number of bytes sent.

long nTotal

The approximate total number of bytes in the message.

Remarks

This event can be used to display the progress of the Send() method.

NOTE: This event is fired during the transmission of a message. During the transmission the object manipulates its data internally and assumes that its data will not be manipulated by any other process during this time. Accessing the object while a transmission is in progress can lead to unpredictable results and is not recommended. The only exception to this rule is the Cancel() method, which may be called during the transmission, to abort the process.

See Also

Cancel() Method
Send() Method


POP3 Usage

ProgID | EasyMail.POP3.4
CLSID | 2FA88EA1-99B6-11d2-B3C3-00A0CC3A50B9

EasyMail POP3 is a lightweight COM object which which allows you to retrieve Internet e-mail from mail servers supporting the POP3 protocol. It can be used for server side processing in ASP files, and Perl scripts. It can also be used in any other COM compatible application. i.e.: Internet Explorer, VB, Delphi, etc...

Usage in your application development system:

The program id for this object is "EasyMail.POP3.4"

In order to use the object, you will have to create it in your code. The POP3 object is used like an OLE Automation server or COM object. Although the method for creating an COM object is different within each development system, they all support it.

In VB the command to create an object is "CreateObject()" and is used like this:

Set POP3 = CreateObject(EasyMail.POP3.4")

After the object is created, you can access all of its properties and methods as usual:

POP3.Account="jdoe"
... set other properties ...
POP3.Download(2)
...

The samples section of this documentation contains sample code snippets for various development systems.

The examples in this section use VB syntax.


POP3 Objects

POP3 Collection Objects

The POP3 object manages many collections of similar objects. For example, after messages have been downloaded, the control contains a collection of messages. For each message in the collection, the control contains a collection of attachments and a collection of recipients.

To allow the programmer to easily traverse through these collections, the POP3 control supports a collection object interface. Collection objects allow you to easily manage a lists of similar objects. If you have already used database access objects, such as ADO, you are already familiar with collection objects.

Once you understand collection objects, you will see why we chose to implement them -- they are just so easy to work with.

Collection objects support standard methods and properties which allow the programmer to iterate through and access specific members of a collection.

A collection object is accessed as a property of its parent object. For example, in our case, the main POP3 object has a Messages property. This property does not contain a string or number, instead it contains another object. In this case it is the Messages object.

The Messages object is a collection object. It manages a collection of messages. The Messages object has properties and methods which allow you to iterate through the messages and access any item in the collection.

For example, the Messages object contains a Count property which returns the number of messages in the collection. It also contains an Item(pos) method, which allows access to message number pos in the collection.

To get the count of messages stored in the collection object you would access the Count property like this:

NumMessages=POP3.Messages.Count

Each member of a collection is a standard object having its own properties and methods. These objects may even contain other collection objects. In our case, the members of the Messages object collection are Message objects.

You would access the second message stored in the POP3 object like this:

Sender = POP3.Messages.Item(2).From

The Item() method is the default method of the Messages object, so you can omit it and take a shortcut like this:

Sender = POP3.Messages(2).From

Each Message object contains two collection objects, one for the recipients and one for the attachments. To get the count of attachments for the second message in the Messages collection, you would write something like this:

AttCount = POP3.Messages(2).Attachments.Count

To get the file name of the first attachment of the second message:

FileName = POP3.Messages(2).Attachments(1).FileName

Remember that each collection object manages a collection of objects. You could also set variables to these objects to simplify your code. i.e.

Dim Message As Object
Dim Attachment As Object

Set Message = POP3.Messages(2)
Set Attachment = Message.Attachments(1)
FileName = Attachment.FileName

Collection objects also support a special shortcut to allow you to iterate through them very easily.

For Each Message In POP3.Messages
   For Each Attachment In Message.Attachments
      Debug.Print Attachment.FileName
   Next Attachment
Next Message

For more information on collection objects check out Microsoft's MSDN on-line at http://www.microsoft.com/msdn.


POP3 Main Object

The POP3 Main object includes properties, methods and events global to the POP3 session. The Main object also includes a Messages property that contains the POP3 Messages collection object which can be used to manage the collection of downloaded messages.

See Also

POP3 Collection Objects
Messages Property (POP3 Main Object)
POP3 Messages Object


Account Property (POP3 Main)

Account Property

POP3 Main Object

The user account name on the mail server.

Type: String

Remarks

Use this property to specify the account / mailbox name on the server. The account name is the first part of the e-mail address.

For example, if you want to download mail sent to jdoe@domain.com, you would specify "jdoe" as the account.

This property is required to retrieve mail.

See Also

Password Property


AuthMode Property (POP3 Main)

AuthMode Property

POP3 Main Object

Specifies the authentication mode to use when connecting to a POP3 mail account.

Type: Long

May any combination of the following values:

Value | Meaning
0 | Simple authentication (default) Password is sent in clear text.
16 | APOP authentication
256 | Allow automatic degradation of the authentication mode

Remarks

With APOP authentication, the password itself is never sent to the remote mail server. Instead, a digest is created using the RSA MD5 algorithm. This digest is based on the password specified in the Password property and a unique value supplied by the POP3 mail server during the connection. This digest is sent to the mail server in lieu of the password. Because the unique value supplied by the mail server changes with each connection, APOP authentication ensures that a different digest will be sent each time you log onto the sever. This seriously reduces the ability for a network sniffing program to capture your password.

All mail servers do not support APOP. If APOP authentication is selected you may also want to enable the automatic degradation of the authentication mode. With these two options selected, the POP3 object will first try to authenticate the connection with APOP, and if the server does not support APOP, simple authentication will be used. To enable both options, "Or" them together

e.g.

SMTP.AuthMode = 16 Or 256

See Also

Connect() Method
Password Property


LicenseKey Property (POP3 Main, IMAP4 Main)

LicenseKey Property

POP3 Main Object, IMAP4 Main Object

The license key to be used with the object.

Type: String

Remarks

Holds the license key for the object. If the LicenseKey property is not assigned a valid license key, the object will operate in demo mode.

While in demo mode, the object can operate in one of two ways depending on the setting of the DemoMode property.

To take the object out of demo mode, you must assign it a valid license key. License keys can be obtained from Quiksoft Corporation.

See Also

Licensing
DemoMode Property


MailServer Property (POP3 Main)

MailServer Property

POP3 Main Object

Sets the address of the mail server to communicate with.

Type: String

Remarks

Set this property to the name of your mail server. e.g. "mail.domain.com".

This property is required before mail can be retrieved.

See Also

MailPort Property


Messages Property (POP3 Main)

Messages Property

POP3 Main Object

This property contains the POP3 messages collection object.

Type: Object

See Also

POP3 Collection Objects
Messages Object


Password Property (POP3 Main)

Password Property

POP3 Main Object

The password of the user account on the mail server.

Type: String

Remarks

Use this property to specify the password of the account / mailbox you are accessing on on the server.

Is is important to note that with the default implementation of the POP3 protocol, passwords are sent across the Internet as clear text. To add a level of security to your mail application, consider using APOP, which encrypts the password before it is sent across the Internet. APOP is only supported on some POP3 mail servers.

This property is required to retrieve mail.

See Also

AuthMode Property


PreferredBodyFormat Property (POP3 Main)

PreferredBodyFormat Property

POP3 Main Object

Specifies preferred format of the message body.

Type: Long

This property may be set to one of the following values:

Value | Meaning
0 | Plain Text (default)
1 | HTML
2 | RTF

Remarks

With MIME, it is possible to have multiple message bodies, each in a different format. The POP3 object only stores message bodies in one format. If the preferred type is not available the next richest format is obtained.

The ContentType and ContentSubType properties of the POP3 Message object can be used to determine what format is available.

e.g. text/html, text/rtf, text/plain

See Also

ContentType Property (POP3 Message Object)
ContentSubType Property (POP3 Message Object)


SystemUserName Property (POP3 Main)

SystemUserName Property

POP3 Main Object

The name of the user account in which the object is running.

Type: String

Remarks

If the object is running in a security context, such as on an NT server, this property will contain the user name of that account.

This property is read only.


TempDirectory Property (POP3 Main)

TempDirectory Property

POP3 Main Object

Specifies the temporary directory which the object will use to temporarily store files which have been downloaded.

Type: String

Remarks

If no value is specified for this property, the system's default temporary directory is used.

Temporary Message Storage

If the DownloadMessages() method was called with the option to "save full message source", the temporary message source files will be stored in this directory. The full path and file name of the temporary message files can be obtained from the TempMsgSourceFile property of the POP3 Message object.

Temporary Attachment Storage

The temporary attachment files are decoded and stored in files with the same name as the attachments original filename. Since multiple attachments can have the same filename, to avoid name conflicts, the temp files are placed in object chosen subdirectories beneath the specified directory. To get the fully qualified path and filename of the temporary file, use the TempFileName property of the POP3 Attachment object.

If the specified directory does not exist, it will be automatically created. The security context of the POP3 object must have create, write and delete access in the directory specified.

Root directories are not allowed.

See Also

TempFileName Property (POP3 Attachment Object)
TempMsgSourceFile Property (POP3 Message Object)


Cancel Method (POP3 Main)

Cancel Method

POP3 Main Object

Cancels downloading of messages or message headers.

void Cancel(long nReserved)

Parameters

long nReserved

Must be set to zero.

Remarks

The current message is finished before the operation is canceled.

See Also

DownloadMessages() Method
DownloadHeaders() Method


Connect Method (POP3 Main)

Connect Method

POP3 Main Object

Connects to the POP3 mail server.

long Connect()

Parameters

None

Return Values

Zero if successful, non zero if an error occurred.

Error Codes:

If the method fails, it will return one of the following error codes:

Value | Meaning
1 | Error connecting to host
2 | Bad user name
4 | Bad user name or password
6 | Already connected to a mail server
128 | Could not create thread
1024 | No authorization mode

Remarks

The Connect() method establishes a connection with the POP3 mail server specified in the MailServer property and opens the mailbox specified in the Account property. If a connection is already established with any POP3 server, regardless of the account, the method returns an error. Use the Disconnect method prior to the Connect() method, to ensure that you are disconnected prior to connecting.

The status of the connection process can be monitored with the ConnectLog() event.

NOTE: This method creates a worker thread to establish the connection, and uses your application's main thread to process Windows messages until the connection is complete. This architecture allows your your application to be responsive while the connection is in progress, but prevents the method from returning until the connection is complete. During the connection the worker thread will be manipulating the object and assumes that the object will not be manipulated by any other process during this time. Accessing the object while a connection is in progress can lead to unpredictable results and is not recommended.

See Also

MailServer Property
Account Property
Password Property
Disconnect() Method
AuthMode Property


DeleteSingleMessage Method (POP3 Main)

DeleteSingleMessage Method

POP3 Main Object

Marks a message for deletion without downloading it first.

long DeleteSingleMessage(long nMsg)

Parameters

long nMsg

The messages ordinal position in the mailbox.

Return Values

Returns zero if successful or one of the following error codes if an error occurs:

Value | Meaning
3 | In progress
5 | Error parsing
8 | Connection lost
9 | Exception
16 | Not connected
23 | Could not find or delete the specified message
32 | Socket error
64 | Unexpected error
128 | Could not create thread
512 | Out of memory
1055 | Invalid response

Remarks

Messages marked for deletion are not automatically deleted until the connection with the POP3 server is terminated by calling the Disconnect() method of the POP3 Main object. Use the RollBack() method of the POP3 Main object to unmark all messages marked for deletion.

See Also

DeleteFromServer() Method (POP3 Message Object)
Disconnect() Method
RollBack() Method


Disconnect Method (POP3 Main)

Disconnect Method

POP3 Main Object

Disconnects from the connected POP3 mail server.

long Disconnect()

Parameters

None

Return Values

Zero if successful, non zero if an error occurred.

Error Codes:

If the method fails, it will return one of the following error codes:

Value | Meaning
8 | Connection lost
128 | Could not create thread

Remarks

The Disconnect() method disconnects from the connected POP3 mail server. If no connection is established, or if an established connection was unexpectedly dropped, the method will return an error.

If the Disconnect() method is successful, any messages marked for deletion on the POP3 mail server, will be permanently deleted.

NOTE: This method creates a worker thread to complete the disconnection, and uses your application's main thread to process Windows messages until the disconnection is complete. This architecture allows your your application to be responsive while the disconnection is in progress, but prevents the method from returning until the disconnection is complete. During the disconnection the worker thread will be manipulating the object and assumes that the object will not be manipulated by any other process during this time. Accessing the object while a disconnection is in progress can lead to unpredictable results and is not recommended.

See Also

Connect() Method


DownloadHeaders Method (POP3 Main)

DownloadHeaders Method

POP3 Main Object

Downloads all message headers from the connected POP3 mail server account.

long DownloadHeaders()

Parameters

None

Return Values

Returns zero if successful or non-zero if an error occurred.

If the method fails it will return one of the following error codes:

Value | Meaning
3 | In progress
5 | Error parsing message
7 | Cancelled
8 | Connection lost
9 | Exception
16 | Not connected
128 | Could not create thread
512 | Out of memory

Remarks

Some mail servers do not support retrieval of full header information, therefore, only the sizes of each message are provided. After a successful call to the DownloadHeaders() method, you should check the MessageStatusFlag property of the POP3 Message object, to find out what information was actually downloaded.

This method will not delete any existing messages from the POP3 Messages object. If you wish to delete previously downloaded messages from the object call the Delete() or DeleteAll() methods of the POP3 Messages object.

If the POP3 Messages object already contains messages, the newly downloaded headers will be appended to the list. Each message which was downloaded prior to the call to DownloadHeaders() will be flagged as disconnected by the DownloadHeaders() method. See the MessageStatusFlag property of the POP3 Message object for more information.

To cancel a download, call the Cancel() method.

NOTE: This method creates a worker thread for downloading mail headers, and uses your applications main thread to process Windows messages until the download is complete. This architecture allows your your application to be responsive while the download is in progress, but prevents the method from returning until the download is complete. During the download the worker thread will be manipulating the object and assumes that the object will not be manipulated by any other process during this time. Accessing the object while a download is in progress can lead to unpredictable results and is not recommended. The only exception to this rule is the Cancel() method, which may be called during a download, to abort the process.

See Also

Message Headers
DownloadMessages() Method
Cancel() Method
MessageStatusFlag Property (POP3 Messages Object)


Download Messages (POP3 Main)

Download Messages

POP3 Main Object

Downloads all messages from the connected POP3 mail server account.

void DownloadMessages(long nOptions)

Parameters

long nOptions

May be set to one of the following values:

Value | Meaning
1 | Save full message source. A temporary file will be created containing the source of the message. The fully qualified path and filename of the temporary file can be retrieved from the TempMsgSourceFile property of the POP3 Message Object.
2 | Mark each message for deletion after it has been successfully downloaded.

Return Values

Returns zero if successful or non-zero if an error occurred.

If the method fails it will return one of the following error codes:

Value | Meaning
3 | In progress
5 | Error parsing message
7 | Cancelled
8 | Connection lost
9 | Exception
21 | Message deleted
128 | Could not create thread
512 | Out of memory

Remarks

Messages marked for deletion are not automatically deleted until the connection with the POP3 server is terminated by calling the Disconnect() method. Use the RollBack() method to unmark any messages marked for deletion.

This method will not delete any existing messages from the POP3 Messages object. If you wish to delete previously downloaded messages from the object call the Delete() or DeleteAll() methods of the POP3 Messages object.

If the POP3 Messages object already contains messages, the newly downloaded messages will be appended to the list. Each message which was downloaded prior to the call to DownloadMessages() will be flagged as disconnected by the DownloadMessages() method. See the MessageStatusFlag property of the POP3 Message object for more information.

To cancel a download call the Cancel() method.

NOTE: This method creates a worker thread for downloading mail messages, and uses your applications main thread to process Windows messages until the download is complete. This architecture allows your your application to be responsive while the download is in progress, but prevents the method from returning until the download is complete. During the download the worker thread will be manipulating the object and assumes that the object will not be manipulated by any other process during this time. Accessing the object while a download is in progress can lead to unpredictable results and is not recommended. The only exception to this rule is the Cancel() method, which may be called during a download, to abort the process.

See Also

Cancel() Method
DownloadHeaders() Method
Disconnect() Method
RollBack() Method
TempMsgSourceFile Property (POP3 Message Object)
DownloadMessage Method (POP3 Message Object)
DeleteFromServer Method (POP3 Message Object)


DownloadSingleMessage Method (POP3 Main)

DownloadSingleMessage Method

POP3 Main Object

Downloads one message from the server.

long DownloadSingleMessage(long nMsg)

Parameters

long nMsg

The messages ordinal position in the mailbox.

Return Values

If successful, this method returns the index of the new message in the Messages collection object. If an error occurs, this method will return one of the following negative error codes:

Value | Meaning
-3 | In progress
-5 | Error parsing
-8 | Connection lost
-9 | Exception
-16 | Not connected
-32 | Socket error
-64 | Unexpected error
-128 | Could not create thread
-256 | File IO error
-512 | Out of memory
-1055 | Invalid response

Remarks

This method downloads a single message from the server. The message data is placed into a new Message object which is appended to the Messages collection object. To download all messages from the server, use the DownloadMessages() method.

See Also

POP3 Messages Object
POP3 Message Object
DownloadMessages() Method
DownloadSingleMessageHeaders() Method
DownloadMessage() Method (POP3 Message Object)


DownloadSingleMessageHeaders Method (POP3 Main)

DownloadSingleMessageHeaders Method

POP3 Main Object

Downloads the headers of a single message from the server.

long DownloadSingleMessageHeaders(long nMsg)

Parameters

long nMsg

The messages ordinal position in the mailbox.

Return Values

If successful, this method returns the index of the new message in the Messages collection object. If an error occurs, this method will return one of the following negative error codes:

Value | Meaning
-3 | In progress
-5 | Error parsing
-8 | Connection lost
-9 | Exception
-16 | Not connected
-32 | Socket error
-64 | Unexpected error
-128 | Could not create thread
-256 | File IO error
-512 | Out of memory
-1055 | Invalid response

Remarks

This method downloads the headers of a single message from the server. The header data is placed into a new Message object which is appended to the Messages collection object.

See Also

POP3 Messages Object
POP3 Message Object
DownloadHeaders() Method
Message Headers


GetDownloadableCount Method (POP3 Main)

GetDownloadableCount Method

POP3 Main Object

Returns the number of available messages on the connected POP3 mail server account.

long GetDownloadableCount()

Parameters

None

Return Values

Returns the number of available messages on the connected POP3 mail server account. If no connection is active, the method returns -1.

See Also

Connect() Method
GetDownloadableSize() Method


GetDownloadableSize Method (POP3 Main)

GetDownloadableSize Method

POP3 Main Object

Returns the total size all available messages on the connected POP3 mail server account.

long GetDownloadableSize()

Parameters

None

Return Values

Returns the total size in bytes of all available messages on the connected POP3 mail server account. If no connection is active, the method returns -1.

See Also

Connect() Method
GetDownloadableCount() Method


GetMessageID Method (POP3 Main)

GetMessageID Method

POP3 Main Object

Returns the server's unique id for a message.

string GetMessageID(long nMsg)

Parameters

long nMsg

The messages ordinal position in the mailbox.

Return Values

If this method is successful, it will return the server's unique id for the message. If an error occurs, the string "-ERR" followed by an error description will be returned.

Remarks

It should be noted that the returned id is created and maintained by the server. This id uniquely identifies a message on the server and is not associated with any RFC-822 "MessageID:" header that may be found in the message.

See Also

GetMessageNumFromID() Method


GetMessageNumFromID Method (POP3 Main)

GetMessageNumFromID Method

POP3 Main Object

Returns the ordinal position of a message given its unique id.

long GetMessageNumFromID(string strID)

Parameters

string strID

The unique id of the message on the server.

Return Values

If this method is successful, it will return the ordinal position of the message on the server. If an error occurs, one of the following negative error codes will be returned:

Value | Meaning
-3 | In progress
-5 | Error parsing
-8 | Connection lost
-9 | Exception
-16 | Not connected
-24 | Could not find the specified message
-32 | Socket error
-64 | Unexpected error
-128 | Could not create thread
-512 | Out of memory
-1055 | Invalid response

Remarks

The unique id expected by this method is the same id as returned by the GetMessageID() method. It should be noted that this id is not associated with any "MessageID:" header found in the message.

See Also

GetMessageID() Method


GetMessageSize Method (POP3 Main)

GetMessageSize Method

POP3 Main Object

Returns the size of a message on the server.

long GetMessageSize(long nMsg)

Parameters

long nMsg

The messages ordinal position in the mailbox.

Return Values

This method returns the size of the message on the server or one of the following negative error codes if an error occurs:

Value | Meaning
-3 | In progress
-5 | Error parsing
-8 | Connection lost
-9 | Exception
-16 | Not connected
-32 | Socket error
-64 | Unexpected error
-128 | Could not create thread
-256 | File IO error
-512 | Out of memory
-1055 | Invalid response

Remarks

Use this method to get the size of a message prior to downloading it.

See Also

Size Property (POP3 Message Object)


GetSocketHandle Method (POP3 Main)

GetSocketHandle Method

POP3 Main Object

Returns the socket handle of the current connection with the server.

long GetSocketHandle()

Parameters

None

Return Values

Returns the socket handle of the current connection with the server. If no connection exists, zero is returned.


LoadMessage Method (POP3 Main)

LoadMessage Method

POP3 Main Object

Loads and parses an e-mail message from a disk file.

void LoadMessage(string strFilename, long nFlag)

Parameters

string strFilename

The name of the file to load.

long nFlag

Reserved, must be set to zero.

Return Values

If successful, the method returns a positive number indicating the message's position in the POP3 Messages object. If the method fails, it will return one of the following error codes:

Value | Meaning
-3 | In progress
-5 | Error parsing message
-9 | Exception
-256 | File IO error.
-512 | Out of memory

Remarks

This method was added in version 3,0,0,4 and is not supported in prior versions of the POP3 object.

The input file must be a standard e-mail message, formatted to the specifications of RFC 822.

The LoadMessage() method is synchronous, that is, it will not return until the message has been loaded or an error occurs. Because of this, the Cancel() method, does not apply to this operation.

The TempMsgSourceFile property of the resulting message object will be empty. The MessageStatusFlag will be set to a value of 20, indicating that the message is complete and the session is terminated.

This method can be called without affecting the state of any active POP3 session which may be active.


Ping Method (POP3 Main)

Ping Method

POP3 Main Object

Sends a void command to the server to keep the connection alive.

void Ping()

Parameters

None

Remarks

After a certain period of inactivity, the remote POP3 mail server will time-out and terminate the connection. Use the Ping() method to periodically force activity which will keep the connection alive. The amount of time which a POP3 server will wait before terminating the connection varies with each POP3 server.


RollBack Method (POP3 Main)

RollBack Method

POP3 Main Object

Unmarks all messages marked for deletion on the POP3 mail server.

long RollBack()

Parameters

None

Return Values

Zero if successful, non zero if an error occurred.

Error Codes:

If the method fails, it will return one of the following error codes:

Value | Meaning
16 | Not connected
64 | An unexpected error has occurred

Remarks

This method should not be called during a download.

See Also

DownloadMessages() Method
DeleteFromServer() Method (POP3 Message Object)


ConnectLog Event (POP3 Main)

ConnectLog Event

POP3 Main Object

Echoes POP3 transactions as they are processed. Useful for debugging or logging purposes.

ConnectLog(string strText, long nReserved)

Parameters

string strText

A textual indication of the event

long nReserved

Reserved for future use

Remarks

This event is fired periodically during the connection process.

NOTE: You should not call other methods on the POP3 object while handling this event.

See Also

LogFile Property
EventLogging Property


StatusMessage Event (POP3 Main)

StatusMessage Event

POP3 Main Object

Displays status messages useful for display or progress monitoring.

StatusMessage(string strText, long nParam1, long nParam2, long nParam3)

Parameters

string strText

The message text

long nParam1

The meaning of this parameters value depends on the value of nParam3

long nParam2

The meaning of this parameters value depends on the value of nParam3

long nParam3

Indicates the type of message. May be one of the following values:

Value

Meaning

1

Download is beginning. This message is sent at the beginning of a batch download.

The value of nParam1 is the number of messages being downloaded and the value of nParam2 contains the total size, in bytes, of the messages being downloaded.

2

Connection status. This message is sent multiple times during the connection process.

The values of nParam1 and nParam2 are not used.

4

Download status. This message is sent once for each message being downloaded.

The value of nParam1 is the message number currently being downloaded and the value of nParam2 is the total number of messages being downloaded.

8

Error.

The value of nParam1 is the error code. If an extended error code is available it will be stored in nParam2. If an extended error code is not available, nparam2 will be set to zero.

16

Download status detail. This message is sent multiple times for each message being downloaded.

The value of nParam1 is the cumulative downloaded bytes of the message and the value of nParam2 is the total number of bytes in the message.

Remarks

This event is fired during certain POP3 operations.

NOTE: You should not call other methods on the POP3 object while handling this event.

See Also

LogFile Property
EventLogging Property


POP3 Messages Object

The POP3 Messages object is a collection object used to manage the collection of downloaded messages. The Item() method of this object, allows access to an array of Message objects. Each Message objects can be used to examine and perform operations on messages which have been downloaded.

See Also

POP3 Collection Objects
POP3 Message Object


Count Property

All Collection Objects

Returns the count of objects in the collection.

Type: Long

Remarks

This property is read-only.


Item Method

All Collection Objects

Returns a reference to an object in the collection.

object Item(long nIndex)

Parameters

long nIndex

The index of the item in the collection you wish to retrieve.

Return Values

The Item() method returns an object variable of the type managed by the collection.

Remarks

This is the default method of the collection object.


Delete Method (POP3 Messages)

Delete Method

POP3 Messages Object

Deletes an item from the POP3 Messages collection object.

void Delete(long nItem)

Parameters

long nItem

An index into the collection object, representing the message to be deleted from the collection.

Remarks

The Delete() method deletes an item from the collection of downloaded messages. When an item is deleted, it is removed from the object and any resources that it was consuming are released. Deleting an item causes an immediate reindex of the items in the collection, reducing the value of the Count property by one.

For example if there are 8 messages in the collection:

cnt = Messages.Count  'stores 8 in cnt
Messages.Delete(4) 'deletes the fourth message
Set Message = Messages(8) 'causes an error

This code will cause an error. After deleting message number four, there are only seven messages left in the collection. Referencing message number 8 will cause an error.

Calling the Delete() method does not delete the messages from the POP3 mail server. To delete messages from the POP3 mail server, use the DeleteFromServer() method of the POP3 Message object, or pass the appropriate parameter to the DownloadMessages() method of the POP3 Main object.

To delete all items, see the DeleteAll() method.

See Also

DeleteFromServer() Method (POP3 MessageObject)
DownloadMessages() Method (POP3 Main Object)
DeleteAll() Method


DeleteAll Method (POP3 Messages)

DeleteAll Method

POP3 Messages Object

Deletes all items from the POP3 Messages collection object.

void DeleteAll()

Parameters

None

Remarks

The DeleteAll() method deletes all items from the collection of downloaded messages. When an item is deleted, it is removed from the object and any resources that it was consuming are released. After calling this method the Count property of the Messages object will return zero.

Calling the DeleteAll() method does not delete the messages from the POP3 mail server. To delete messages from the POP3 mail server, use the DeleteFromServer() method of the POP3 Message object, or pass the appropriate parameter to the DownloadMessages() method of the POP3 Main object.

To delete one item, see the Delete() method.

See Also

DeleteFromServer() Method (POP3 MessageObject)
DownloadMessages() Method (POP3 Main Object)
Delete() Method


POP3 Message Object

The POP3 Message object includes properties and methods used to examine and perform actions on a single downloaded message. Among its other properties, the Message object includes a Recipients property and an Attachments property.

The Recipients property contains the POP3 Recipients collection object which can be used to manage the collection of recipients designated by the downloaded message.

The Attachments property contains the POP3 Attachments collection object which can be used to manage the collection of attachments to the downloaded message.

See Also

POP3 Collection Objects
POP3 Messages Object
POP3 Recipients Object
POP3 Attachments Object


Attachments Property (POP3 Message)

Attachments Property

POP3 Message Object

This property contains the POP3 Attachments collection object.

Type: Object

See Also

POP3 Collection Objects
Attachments Object


BodyText Property (POP3 Message)

BodyText Property

POP3 Message Object

Contains the body text of the message.

Type: String

Remarks

This property is read-only.

See Also

PreferredBodyFormat Property (POP3 Main Object)


CharSet Property (POP3 Message, , IMAP4 Message)

CharSet Property

POP3 Messages Object, IMAP4 Message Object

Contains the name of the character set that was used to compose the message.

Type: String

Remarks

The CharSet property contains the name of the character set that was used to compose the message.

e.g. US-ASCII, ISO-8859-*, ISO-2022-JP.

The value for this property is taken from the optional "charset" parameter of the Content-Type message header. This header only appears in MIME formatted messages.

e.g. This sample content-type header record:

Content-Type: text/plain; charset="iso-8859-1"

would set the CharSet property to "iso-8859-1"

To get the raw Content-Type header text see the Headers property.

This property is read-only.

See Also

Message Headers
Headers Property
ContentType Property
ContentSubType Property


ContentSubType Property (POP3 Message, IMAP4 Message)

ContentSubType Property

POP3 Message Object, IMAP4 Message Object

Contains the content sub type of the message.

Type: String

Remarks

The ContentSubType property contains the sub content type which is extracted from the "Content-Type" message header. This header only appears in MIME formatted messages.

e.g. This sample content-type header record:

Content-Type: text/plain; charset="iso-8859-1"

would set the ContentSubType property to "plain"

To get the raw Content-Type header text see the Headers property.

This property is read-only.

See Also

Message Headers
Headers Property
ContentType Property
CharSet Property


ContentType Property (POP3 Message, IMAP4 Message)

ContentType Property

POP3 Message Object, IMAP4 Message Object

Contains the content type of the message.

Type: String

Remarks

The ContentType property contains the primary content type which is extracted from the "Content-Type" message header. This header only appears in MIME formatted messages.

e.g. This sample content-type header record:

Content-Type: text/plain; charset="iso-8859-1"

would set the ContentType property to "text"

To get the raw Content-Type header text see the Headers property.

This property is read-only.

See Also

Message Headers
Headers Property
ContentSubType Property
CharSet Property
PreferredBodyFormat (POP3 Main Object)


Date Property (POP3 Message, IMAP4 Message)

Date Property

POP3 Message Object, IMAP4 Message Object

Contains the date and time of the the message.

Type: String

Remarks

This property contains the date and time that the message was created. It also contains information on the time zone used to calculate the date and time.

This property is read-only.

See Also

Message Headers


From Property (POP3 Message, IMAP4 Message, IMAP4 Envelope)

From Property

POP3 Message Object, IMAP4 Message Object, IMAP4 Envelope Object

Contains the name of the message sender.

Type: String

Remarks

The From property contains the friendly name of the message sender if available.

This property is read-only.

See Also

Message Headers
FromAddr Property


FromAddr Property (POP3 Message, IMAP4 Message, IMAP4 Envelope)

FromAddr Property

POP3 Message Object, IMAP4 Message Object, IMAP4 Envelope Object

Contains the e-mail address of the message sender.

Type: String

Remarks

The FromAddr property contains the e-mail address of the message sender.

The value of this property is taken from the "From:" message header.

This property is read-only.

See Also

Message Headers
From Property
ReplyToAddr Property


Headers Property (POP3 Message, IMAP4 Message)

Headers Property

POP3 Message Object, IMAP4 Message Object

Contains the headers of the message.

Type: String

Remarks

This property contains the entire message header block.

This property is read-only.

See Also

Message Headers


MessageIDProperty (POP3 Message, IMAP4 Message)

MessageID Property

POP3 Message Object, IMAP4 Message Object

Contains the message id.

Type: String

Remarks

The message id is taken from the MessageID header record.

e.g. This sample Message-ID header record:

Message-ID: <B0000069946@mail.domain.com>

would set the MessageID property to "<B0000069946@mail.doamin.com>"

The message id contained in the header record may not be unique to the particular message.

This property is read-only.

See Also

Message Headers
Headers Property
IMAPID Property (IMAP Envelope Object)


MessageStatusFlag (POP3 Message)

MessageStatusFlag

POP3 Message Object

Contains flags which indicate the status of the message.

Type: Long

May be any combination of the following values:

Value | Meaning
1 | Message contains size only
2 | Message contains complete headers
4 | Message is complete
8 | Message has been flagged for deletion from the server
16 | The session which downloaded this message has terminated.

Remarks

A call to the DownloadHeaders() method of the POP3 Main object, normally causes the full header information of each message to be downloaded. Some POP3 servers do not support this and may only send the size of each message. The value of the MessageStatusFlag property provides information on what parts of a particular message have been downloaded.

Once a message has been flagged for deletion from the server, certain functions of that message will fail. For example, calling the DownloadMessage() method of the POP3 Message object on a message which has been flagged for deletion from the server, will generate an error. The value for the MessageStatusFlag property indicates if a message has been flagged for deletion from the server.

Certain message operations are only valid during the same session in which they were downloaded. See The POP3 Protocol for more information on POP3 sessions.

This property is read-only.

See Also

The POP3 Protocol
DownloadMessage() Method (POP3 Message Object)
DownloadHeaders() Method (POP3 Main Object)


Priority Property (POP3 Message, IMAP4 Message)

Priority Property

POP3 Message Object, IMAP4 Message Object

Contains the priority of the message.

Type: String

Remarks

The value of this property is read from the message header "X-Priority". Different mail readers may set or interpret the X-Priority setting differently. Some may not set or interpret it at all. The popular readers set or interpret "4"=low, "3"=normal and "1"=high.

See Also

Message Headers


Recipients Property (POP3 Message)

Recipients Property

POP3 Message Object

This property contains the POP3 Recipients collection object.

Type: Object

See Also

POP3 Collection Objects
Recipients Object


ReplyTo Property (POP3 Message, IMAP4 Message, IMAP4 Envelope)

ReplyTo Property

POP3 Message Object, IMAP4 Message Object, IMAP4 Envelope Object

Contains the friendly name of the entity specified to receive all replies to this message.

Type: String

Remarks

The reply-to value is taken from the "Reply-To:" message header.

This property is read-only.

See Also

Message Headers
ReplyToAddr Property
FromAddr Property


ReplyToAddr Property (POP3 Message, IMAP4 Message, IMAP4 Envelope)

ReplyToAddr Property

POP3 Message Object, IMAP4 Message Object, IMAP4 Envelope Object

Contains the reply-to address specified in the message.

Type: String

Remarks

The reply-to address is taken from the "Reply-To:" message header. If this value is specified, the sender wishes all replies to this message to go to the reply-to address instead of the from address.

This property is read-only.

See Also

Message Headers
ReplyTo Property
FromAddr Property


Size Property (POP3 Message, IMAP4 Message, IMAP4 Envelope)

Size Property

POP3 Message Object, IMAP4 Message Object, IMAP4 Envelope Object

Contains the size of the mail message.

Type: Long

Remarks

This property contains the size of the message in bytes. The size represents all parts of the message, including headers and any attachments.

This property is read-only.


Subject Property (POP3 Message, IMAP4 Message, IMAP4 Envelope)

Subject Property

POP3 Message Object, IMAP4 Message Object, IMAP4 Envelope Object

Contains the subject of the message.

Type: String

Remarks

The subject is taken from the "Subject :" message header.

This property is read-only.

See Also

Message Headers
BodyText Property


TempMsgSourceFile Property (POP3 Message)

TempMsgSourceFile Property

POP3 Message Object

Contains the file name of the temporary message source file.

Type: String

Remarks

If the DownloadMessages() method of the POP3 Main Object or the DownloadMessage() method of the POP3 Message Object was called with the option to "save message source", a temporary message source file will be created for each downloaded message. The message source file contains the entire message: headers, body text, attachment data and all. The file is formatted to standard specifications and should be understood by other mail programs.

The temporary message file is automatically deleted when the message is deleted from the object or the object is destroyed.

This property is read-only.

See Also

DownloadMessages() Method (POP3 Main Object)
DownloadMessage() Method (POP3 Message Object)


CreateMessageHandle Method (POP3 Message, IMAP4 Message)

CreateMessageHandle Method

POP3 Message Object, IMAP4 Message Object

Creates a message handle representing the message.

long CreateMessageHandle()

Parameters

None

Return Values

A non-zero message handle if successful, or zero if an error occurred.

Remarks

Resources consumed by the handle will be automatically released when the object is destroyed.

NOTE: Message handles should never be cached. The handle becomes invalid when the object is destroyed or when CreateMessageHandle() is called again. Using an invalid handle can lead to unpredictable results.

See Also

LoadMessageFromHandle() Method (SMTP)


DeleteFromServer Method (POP3 Message)

DeleteFromServer Method

POP3 Message Object

Marks the message for deletion from the server.

long DeleteFromServer()

Parameters

None

Return Values

Zero if successful, non zero if an error occurred.

Error Codes:

If the method fails, it will return one of the following error codes:

Value | Meaning
3 | In progress
8 | Connection lost
18 | Invalid Session
64 | An unexpected error has occurred

Remarks

Messages marked for deletion are not automatically deleted until the connection with the POP3 server is terminated by calling the Disconnect() method of the POP3 Main object. Use the RollBack() method of the POP3 Main object to unmark all messages marked for deletion.

See Also

Disconnect() Method (POP3 Main Object)
RollBack() Method (POP3 Main Object)


DoViewDlg Method (POP3 Message, IMAP4 Message)

DoViewDlg Method

POP3 Message Object, IMAP4 Message Object

Displays a dialog box with the current message loaded for viewing.

long DoViewDlg(long hWnd, string strCaption, long nOptions)

Parameters

long hWnd

A handle to the window which should be used as the parent of the dialog. Passing a value of zero will cause the Desktop window to be used.

string strCaption

The caption to be displayed at the top of the dialog.

long nOptions

May be zero or any combination of the following values:

Value | Meaning
1 | Enable "Delete" button and menu option
2 | Enable "Reply" button and menu option
4 | Enable "Reply All" button and menu option
8 | Enable "Forward" button and menu option

Return Values

Return values less than 64 indicate that the operation completed successfully.

Value | Meaning
1 | Operation completed normally. User closed dialog.
11 | Operation completed normally. User selected delete.
12 | Operation completed normally. User selected reply.
13 | Operation completed normally. User selected reply to all.
14 | Operation completed normally. User selected forward.
100 | Invalid parameter.
101 | A fatal exception occurred
126 | Dialog module not found
127 | Dialog module procedure not found. The dialog module may be corrupted.
1400 | An invalid window handle was specified in the hWnd parameter.

Remarks

The DoViewDlg() method displays a dialog box displaying the current message. The data in the dialog is read-only however the attachments may be copied or saved to another location.

See Also

DoSendDlg() Method (SMTP)


DownloadMessage Method (POP3 Message)

DownloadMessage Method

POP3 Message Object

Downloads a message from the connected POP3 mail server account.

long DownloadMessage(long nOptions)

Parameters

long nOptions

May be set to zero or one of the following values:

Value | Meaning
1 | Save full message source. A temporary file will be created containing the source of the message. The fully qualified path and filename of the temporary file can be retrieved from the TempMsgSourceFile property of the POP3 Message Object.

Return Values

Returns zero if successful or non-zero if an error occurred.

If the method fails it will return one of the following error codes:

Value | Meaning
3 | In progress
5 | Error parsing message
7 | Cancelled
8 | Connection lost
9 | Exception
16 | Not connected
18 | Invalid session
21 | Message deleted
128 | Could not create thread
512 | Out of memory

Remarks

This method will not delete the message from the POP3 mail server. To delete the message, use the DeleteFromServer() method of the POP3 Message object.

NOTE: This method creates a worker thread for downloading the mail message, and uses your applications main thread to process Windows messages until the download is complete. This architecture allows your your application to be responsive while the download is in progress, but prevents the method from returning until the download is complete. During the download the worker thread will be manipulating the object and assumes that the object will not be manipulated by any other process during this time. Accessing the object while a download is in progress can lead to unpredictable results and is not recommended. The only exception to this rule is the Cancel() method, which may be called during a download, to abort the process.

See Also

DownloadHeaders() Method
TempMsgSourceFile Property (POP3 Message Object)
DownloadMessages() Method (POP3 Main Object)


POP3 Recipients Object

Recipients Object

The POP3 Recipients object is a collection object used to manage the collection of recipients designated by the downloaded message. The Item() method of this object, allows access to an array of POP3 Recipient objects. Each Recipient object can be used to examine and perform operations on a recipient of the downloaded message.

See Also

POP3 Collection Objects
POP3 Recipient Object
POP3 Message Object


POP3 Recipient Object (POP3 Main)

POP3 Recipient Object

The POP3 Recipient object includes properties and methods used to examine and perform actions on a single recipient of the downloaded message.

See Also

POP3 Collection Objects
POP3 Recipients Object


Address Property (POP3 Recipient, IMAP4 Recipient)

Address Property

POP3 Recipient Object, IMAP4 Recipient Object

Contains the e-mail address of the recipient.

Type: String

Remarks

The Address property contains the e-mail address of the recipient.

The value of this property is taken from the "To:" or "CC:" message headers. To determine whether this address was specified as a primary recipient or a carbon copy recipient see the Type property.

This property is read-only.

See Also

Message Headers
From Property
Type Property


Name Property (POP3 Recipient, IMAP4 Recipient)

Name Property

POP3 Recipient Object, IMAP4 Recipient Object

Contains the friendly name of the recipient.

Type: String

Remarks

The Name property contains the friendly name of the recipient.

The value of this property is taken from the "To:" or "CC:" message headers. To determine whether this name was specified as a primary recipient or a carbon copy recipient see the Type property.

This property is read-only.

See Also

Message Headers
From Property
Type Property


Type Property (POP3 Recipient, IMAP4 Recipient)

Type Property

POP3 Recipient Object, IMAP4 Recipient Object

Contains the type of the recipient.

Type: Long

May be any one of the following values:

Value | Meaning
1 | Normal recipient
2 | Carbon copy recipient

Remarks

This property is read-only.

See Also

Message Headers
From Property


POP3 Attachments Object

The POP3 Attachments object is a collection object used to manage the collection of attachments to the downloaded message. The Item() method of this object, allows access to an array of POP3 Attachment objects. Each Attachment object can be used to examine and perform operations on the an attachment of the downloaded message.

See Also

POP3 Collection Objects
POP3 Attachment Object
POP3 Message Object


POP3 Attachment Object

Attachment Object

The POP3 Attachment object includes properties and methods used to examine and perform actions on a single attachment to the downloaded message.

See Also

POP3 Collection Objects
POP3 Attachments Object


ContentID Property (POP3 Attachment, IMAP4 Attachment)

ContentID Property

POP3 Attachment Object, IMAP4 Attachment Object

Contains the content id of the attachment.

Type: String

Remarks

The content id is useful for referencing attachment data within the body of the message. A common application is mapping image attachments to their positions within an HTML formatted message. The value of this property is taken from the "Content-ID:" attachment header and is only relevant in MIME formatted messages.

i.e.

Excerpt from HTML message:

<IMG align=baseline alt="" border=0 = hspace=0 src="cid:001501bd99a1$dc3b9a80$0100007f@nec.quiksoft.com">

Excerpt from image attachment in same message:

Content-Type: image/gif
Content-Transfer-Encoding: base64
Content-ID: <001501bd99a1$dc3b9a80$0100007f@nec.quiksoft.com>

This property is read-only.


ContentSubType Property (POP3 Attachment, IMAP4 Attachment)

ContentSubType Property

POP3 Attachment Object, IMAP4 Attachment Object

Contains the content sub type of the attachment.

Type: String

Remarks

The ContentSubType property contains the sub content type which is extracted from the "Content-Type:" attachment header and is only relevant in MIME formatted messages.

e.g. This sample content-type attachment header record:

Content-Type: application/x-zip-compressed; name="smtp.zip"

would set the ContentSubType property to "x-zip-compressed"

This property is read-only.

See Also

ContentType Property


ContentType Property (POP3 Attachment, IMAP4 Attachment)

ContentType Property

POP3 Attachment Object, IMAP4 Attachment Object

Contains the content type of the attachment.

Type: String

Remarks

The ContentType property contains the primary content type which is extracted from the "Content-Type:" attachment header and is only relevant in MIME formatted messages.

e.g. This sample content-type attachment header record:

Content-Type: application/x-zip-compressed; name="smtp.zip"

would set the ContentType property to "application"

This property is read-only.

See Also

ContentSubType Property


Description Property (POP3 Attachment, IMAP4 Attachment)

Description Property

POP3 Attachment Object, IMAP4 Attachment Object

Contains a textual description of the attachment.

Type: String

Remarks

This property is read-only.


Encoding Property (POP3 Attachment, IMAP4 Attachment)

Encoding Property

POP3 Attachment Object, IMAP4 Attachment Object

Contains a description of the encoding of the attachment.

Type: String

Remarks

This property describes the encoding algorithm used to encode the attachment. For example Base 64 or Quoted Printable. The value of this property is taken from the "Content-Transfer-Encoding::" attachment header and is only relevant in MIME formatted messages.

i.e. The following excerpt from an attachment header informs us that the attachment was encoded using Base 64.

Content-Transfer-Encoding: base64

In this case, the Encoding property would be set to "base64".

This property is read-only.

See Also

Message Encoding


FileName Property (POP3 Attachment)

FileName Property

POP3 Attachment Object

Contains the original filename of the attachment.

Type: String

Remarks

The FileName property contains the original filename of the attachment. This property does not indicate that the attachment is saved on disk at this time. To save an attachment to disk, use the Save() method of the POP3 Attachment object.

A temporary file containing the attachment data, is automatically created during the download process. To get the fully qualified path and filename of the temporary file, use the TempFileName property of the POP3 Attachment object. See the TempDirectory property of the POP3 Main object for more information.

If the file name can not be determined the filename "unknown.unk" will be used.

This property is read-only.

See Also

Save Method (POP3 Attachment Object)
TempDirectory Property (POP3 Main Object)
TempFileName Property (POP3 Attachment Object)


Name Property (POP3 Attachment)

Name Property

POP3 Attachment Object

Contains the name of the attachment.

Type: String

Remarks

This property is similar to the FileName property of the POP3 Attachment object, although they are both obtained from separate information specified in the attachment header. The value of this property is taken from the "Content-Type:" attachment header and is only relevant in MIME formatted messages.

The following attachment header shows that both filename and name are specified in the header. They are usually, but not always, the same.

Content-Type: application/x-zip-compressed; name="smtp.zip"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smtp.zip"

This property is read-only.

See Also

FileName Property (POP3 Attachment Object)


Size Property (POP3 Attachment, IMAP4 Attachment)

Size Property

POP3 Attachment Object, IMAP4 Attachment Object

Contains the size of the attachment.

Type: Long

Remarks

The Size property contains the size of the attachment in its decoded state.

This property is read-only.


TempFileName Property (POP3 Attachment)

TempFileName Property

POP3 Attachment Object

The fully qualified path and filename of the decoded, temporary attachment file.

Type: String

Remarks

The directory used to store the temporary attachment files is controlled by the TempDirectory property of the POP3 Main object. The temporary attachment file is automatically deleted when the message is deleted from the object or the object is destroyed.

See Also

TempDirectory Property (POP3 Main Object)


Save Method (POP3 Attachment)

Save Method

POP3 Attachment Object

Decodes and saves the attachment to disk.

long Save(string strFileName, bool bOverwrite)

Parameters

string strFileName

The path and filename of the destination file.

bool bOverwrite

Set this parameter to a non-zero value to overwrite the destination file if it already exists.

Return Values

Zero if successful, non zero if an error occurred.

Error Codes:

If the method fails, it will return one of the following error codes:

Value | Meaning
3 | Path not found
80 | File already exists

Remarks

If the POP3 object is running in a security context, that security context must have rights to create and write in the path specified in the strFileName parameter.

A temporary file containing the attachment data, is automatically created during the download process. See the TempFileName property of the POP3 Attachment object for more information.

See Also

TempFileName Property (POP3 Attachment Object)


IMAP4 Usage

ProgID | EasyMail.IMAP4.4
CLSID | 5D283F11-6538-11D2-81D8-00AA00336A3E

EasyMail IMAP4 is a lightweight COM object which which allows you to retrieve Internet e-mail from mail servers supporting the IMAP4 protocol. It can be used for server side processing in ASP files, and Perl scripts. It can also be used in any other COM compatible application. i.e.: Internet Explorer, VB, Delphi, etc...

Usage in your application development system:

The program id for this object is "EasyMail.IMAP4.4"

In order to use the object, you will have to create it in your code. The IMAP4 object is used like an OLE Automation server or COM object. Although the method for creating an COM object is different within each development system, they all support it.

In VB the command to create an object is "CreateObject()" and is used like this:

Set IMAP4 = CreateObject(EasyMail.IMAP4.4")

After the object is created, you can access all of its properties and methods as usual:

IMAP4.Connect("mail.domain.com")
...

The samples section of this documentation contains sample code snippets for various development systems.

The examples in this section use VB syntax.


IMAP4 Collection Objects

The IMAP4 object manages many collections of similar information. For example, for each e-mail message, the object contains a collection of zero or more attachments, a collection of one or more recipients, etc...

To allow the programmer to easily traverse through these collections, the IMAP4 object supports a collection object interface. Collection objects allow you to easily manage lists of similar information. If you have already used database access objects, such as ADO, you are already familiar with collection objects.

Once you understand collection objects, you will see why we chose to implement them -- they are just so easy to work with.

Collection objects support standard methods and properties which allow the programmer to iterate through and access specific members of a collection.

A collection object is accessed as a property of its parent object. For example, in our case, the main IMAP4 object has an Envelopes property. This property does not contain a string or number, instead it contains another object. In this case it is the Envelopes collection object.

The Envelopes object is a collection object. It manages a collection of envelopes. An IMAP4 envelope contains information about a particular message on the IMAP4 server. The Envelopes object has properties and methods which allow you to iterate through the envelopes and access any envelope in the collection.

For example, the Envelopes object contains a Count property which returns the number of envelopes in the collection. It also contains an Item(pos) method, which allows access to message number pos in the collection.

To get the count of available envelopes you would access the Count property like this:

NumEnvelopes=IMAP4.Envelopes.Count

Each member of a collection is a standard object having its own properties and methods. These objects may even contain other collection objects. In our case, the members of the Envelopes object collection are Envelope objects.

You would access the second envelope like this:

Sender = IMAP4.Envelopes.Item(2).From

The Item() method is the default method of the Envelopes object, so you can omit it and take a shortcut like this:

Sender = IMAP4.Envelopes(2).From

Collection objects also support a special shortcut to allow you to iterate through them very easily.

For Each Envelope In IMAP4.Envelopes
      Debug.Print Envelope.From
Next Envelope

For more information on collection objects check out Microsoft's MSDN on-line at http://www.microsoft.com/msdn.


IMAP4 Basic Operations

The IMAP4 protocol allows you to examine the messages on your server in great detail before they are downloaded to your computer. The IMAP4 object provides several mechanisms to allow you to take advantage of this.

Creating the Object

Dim IMAP4 as Object
Set IMAP4 = CreateObject("EasyMail.IMAP4.4")

Connecting to the Server

IMAP4.Connect("mail.domain.com")

Logging-In and Selecting a Mailbox

IMAP4.Login("username", "password")
IMAP4.SelectMailbox("Inbox")

Downloading a List of Messages

IMAP4.DownloadEnvelopes(1, -1, 0)

Previewing the Properties of the Available Messages

For Each Envelope In IMAP4.Envelopes
    FromAddr = Envelope.From
    Subject = Envelope.Subject
    Size = Envelope.Size
Next Envelope

Downloading a Message

IMAP4.DownloadMessage(1, 0)

Saving the Attachments

For Each Attachment in IMAP4.Message.Attachments
    Attachment.Save("c:\destination folder\" & Attachment.FileName, 0)
Next Attachment

Browsing the List of Recipients

For Each Recipient in IMAP4.Message.Recipients
    Name = Recipient.Name
Next Recipient

Logging Off the System

IMAP4.Logout
IMAP4.Disconnect


IMAP4 Main Object

The IMAP4 Main object includes properties, methods and events global to the IMAP4 session.

See Also

IMAP4 Collection Objects


IMAP4 Standard Error Codes

Standard Error Codes

IMAP4 Main Object

Methods of the IMAP4 Main Object may return one of the following error codes.

Value | Meaning
0 | The operation completed successfully.
1 | The server did not respond.
2 | Server sent a BAD return. Call GetLastErrorString() for reason.
3 | Server sent a NO return. Call GetLastErrorString() for reason.
4 | The buffer needed was not large enough.
5 | One of the parameters send was invalid.
6 | An operation is in progress.
7 | Could not allocate memory.
8 | The object is not connected.
9 | An exception has occurred.
10 | Did not receive all the data expected.


DemoMode Property (POP3 Main, IMAP Main)

DemoMode Property

POP3 Main Object, IMAP4 Main Object

Specifies options when running in demo mode.

Type: Long

May be one of the following values:

Value | Meaning
0 | Change the e-mail message and subject to a "demo" message. (default)
1 | Do not change the message and subject, instead display a "demo dialog."

Remarks

When the object is running in demo mode, this property will allow you to adjust its behavior. In some instances, for example when running the object on a server, it is undesirable to display "demo dialogs."

Once this property has been set, it can not be changed again during the object's instance.

If a valid license key is specified in the LicenseKey property, this property is ignored.

See Also

LicenseKey Property
Licensing


Envelopes Property (IMAP4 Main)

Envelopes Property

IMAP4 Main Object

This property contains the IMAP Envelopes collection object.

Type: Object

See Also

IMAP4 Collection Objects
IMAP4 Envelopes Object
IMAP4 Envelope Object


MailBoxes Property (IMAP4 Main)

MailBoxes Property

IMAP4 Main Object

This property contains the IMAP4 Mailboxes collection object.

Type: Object

See Also

IMAP4 Collection Objects
IMAP4 Mailboxes Object
IMAP4 Mailbox Object


Message Property (IMAP4 Main)

Message Property

IMAP4 Main Object

This property contains the IMAP4 Message object.

Type: Object

See Also

IMAP4 Collection Objects
IMAP4 Message Object


MessageCount Property (IMAP4 Main)

MessageCount Property

IMAP4 Main Object

This property contains the count of messages in the selected mailbox.

Type: Long

Remarks

The value of this property represents the number of messages in the currently selected mailbox. If no mailbox is currently selected, the value of this property is undefined. Mailboxes may be selected with the SelectMailbox() method.

This property may be refreshed by calling the Noop() method.

This property is read-only.

See Also

SelectMailbox() Method
Noop() Method


PerformanceMode Property (IMAP4 Main)

PerformanceMode Property

IMAP4 Main Object

Specifies performance options.

Type: Long

May be one of the following values:

Value | Meaning
0 | Process Windows messages and fire events during operations. (default)
1 | Do not process Windows messages or fire events during operations.

Remarks

Normally this property should be left at its default value of zero.

NOTE: When the PerformanceMode property is set to zero. Each method call will create a worker thread to perform the requested task and use your application's main thread to process Windows messages until the task is complete. This architecture allows your your application to be responsive while the task is in progress, but prevents the method from returning until the task is complete. During the task the worker thread will be manipulating the object and assumes that the object will not be manipulated by any other process during this time. Accessing the object while a task is in progress can lead to unpredictable results and is not recommended.


Recent Property (IMAP4 Main)

Recent Property

IMAP4 Main Object

Specifies the number of messages in the selected mailbox that have not been viewed yet.

Type: Long

Remarks

This property is read-only. The value of this property may be periodically updated by calling the Noop() method.

See Also

SelectMailbox() Method
Noop() Method


TempDirectory Property (IMAP4 Main)

TempDirectory Property

IMAP4 Main Object

Specifies the directory which the object will use to store temporary data.

Type: String

Remarks

If no value is specified for this property, the system's default temporary directory is used.

The specified directory must exist and the security context of the IMAP4 object must have create and write and delete access in the directory specified. Root directories are not allowed.

See Also

TempMsgSourceFile Property (IMAP4 Message Object)


Append Method (IMAP4 Main)

Append Method

IMAP4 Main Object

Uploads a message to a mailbox on the server.

long Append(string strMailBox, long nFlags, string strDate, string strMessage)

Parameters

string strMailBox

Mailbox to upload to. Must be a valid mailbox name as returned by the DownloadMailboxes() method.

long nFlags

Flags to set for the message. May be zero or any combination of the following:

Value | Meaning
1 | Seen
2 | Deleted
4 | Flagged
8 | Answered
16 | Recent
32 | Draft

String strDate

Date to set on the message. Must be in RFC-822 date format. If this parameter is left blank, the current date and time will be used. This parameter is used for the server only and does not affect any RFC-822 date header which may be present in the uploaded message.

string strMessage

RFC-822 message to upload.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

Remarks

This method is not a replacement for the process of sending mail with SMTP. To create and send a new e-mail message to a recipient, use the EasyMail SMTP Object.


Connect Method (IMAP4 Main)

Connect Method

IMAP4 Main Object

Connects to the IMAP4 server.

long Connect(string strServer)

Parameters

string strServer

Name of mail server to connect to. The address can be specified as a literal address like mail.domain.com or specific as a numerical IP address such as 127.0.0.0.

Return Values

Returns zero if successful or one of the standard error codes if a non-sockets error occurs.

If a sockets error occurs, the socket error number will be returned. The returned sockets error may be one of, but is not limited to, the following:

Value | Meaning
10061 | Connection Refused
10049 | Address Not Available

See Also

MailPort Property
Timeout Property
Disconnect() Method
IsConnected() Method


CopyMessages Method (IMAP4 Main)

CopyMessages Method

IMAP4 MAIN Object

Copies one or more messages from the currently selected mailbox to a different mailbox.

long CopyMessages(string strMailbox, long nFirst, long nLast, bool bUID)

Parameters

string strMailbox

Name of mailbox to copy to.

long nFirst

The message number or the unique id of the first message in the range to copy.

long nLast

The message number or unique ID of the last message in the range to copy. This parameter can be set to -1 to indicate that all messages starting at nFirst should be copied.

bool bUID

Specifies whether the values of nFirst and nLast are specified as message numbers or unique IDs.

If this value is set to non zero, the nFirst and nLast parameters should be specified as unique IDs.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

Remarks

The nFirst and nLast parameters may be specified by a message's number or its unique ID. See the section on the IMAP4 protocol for more information on identifying messages.

Set nFirst and nLast to the same message number or ID to copy only one message.

See Also

SelectMailbox() Method


CreateMailbox Method (IMAP4)

CreateMailbox Method

IMAP4 Main Object

Creates a mailbox on the server.

long CreateMailbox(string strMailbox)

Parameters

string StrMailBox

Name of new mailbox to create.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

See Also

DeleteMailbox() Method
RenameMailbox() Method
SelectMailbox() Method


DeleteMailbox Method (IMAP4 Main)

DeleteMailbox Method

IMAP4 MAIN Object

Deletes Mailbox from the server.

long DeleteMailbox(string strMailbox)

Parameters

string strMailBox

Name of mailbox to delete.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

Remarks

The mailbox to delete must be empty or an error will occur.

See Also

RenameMailbox() Method
CreateMailbox() Method


Disconnect Method (IMAP4 Main)

Disconnect Method

IMAP4 Main Object

Disconnects from the mail server.

long Disconnect()

Parameters

None

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

See Also

Connect() Method
IsConnected() Method


DownloadEnvelopes Method (IMAP4 Main)

DownloadEnvelopes Method

IMAP4 Main Object

Downloads one or more message envelopes from the currently selected mailbox.

long DownloadEnvelopes(long nFirst, long nLast, bool bUID)

Parameters

long nFirst

The message number or unique ID of the first message envelope to download.

long nLast

The message number or unique ID of the last message envelope to download. This value can be set to -1 to download all message envelopes starting at nFirst.

bool bUID

Specifies whether the values of nFirst and nLast are specified as message numbers or unique IDs.

If this value is set to non zero, the nFirst and nLast parameters should be specified as unique IDs.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

Remarks

The nFirst and nLast parameters may be specified by a message's number or its unique ID. See the section on the IMAP4 protocol for more information on identifying messages.

Set nFirst and nLast to the same message number or ID to download only one envelope.

If this operation is successful, the downloaded envelopes can be accessed through the Envelopes collection object. Any data already present in the Envelopes collection object is deleted.

See Also

Envelopes Property
Envelopes Collection Object
SelectMailbox() Method


DownloadMailboxes Method (IMAP4 Main)

DownloadMailboxes Method

IMAP4 Main Object

Downloads a list of mailboxes available on the server.

long DownloadMailboxes(long nFlag)

Parameters

long nFlag

If this flag is set to 1 then the only subscribed mailboxes will be downloaded.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

Remarks

If this operation is successful, the list of downloaded mailbox names is available through the Mailboxes collection object.

See Also

SelectMailbox() Method
Subscribe() Method
Unsubscribe() Method
Mailboxes Object


DownloadMessage Method (IMAP4 Main)

DownloadMessage Method

IMAP4 Main Object

Downloads a message from the selected mailbox and parses it into the Message object.

long DownloadMessage(long nMsg, bool bUID);

Parameters

long nMsg

The message number or the unique ID of the message to download.

bool bUID

Specifies whether the value of nMsg is specified as a message number or unique ID. Set this parameter to non-zero if nMsg is specified as a unique ID.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

See Also

Message Object
SelectMailbox() Method


Expunge Method (IMAP4 Main)

Expunge Method

IMAP4 Main Object

Deletes all messages from the selected mailbox that are flagged as deleted.

long Expunge()

Parameters

None

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

See Also

SelectMailbox() Method
ExpungeAndClose() Method


ExpungeAndClose Method (IMAP4 Main)

ExpungeAndClose Method

IMAP4 Main Object

Permanently removes all messages flagged for deletion and closes the currently selected mailbox.

long ExpungeAndClose()

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

Remarks

This method closes the selected mailbox and permanently removes all messages that have the deleted flag set.

It is not necessary to call this method before opening another mailbox or disconnecting. Do not call this method if you wish to leave a mailbox without permanently removing all messages that have the deleted flag set.

See Also

SelectMailbox() Method
Disconnect() Method


GetLastErrorString Method (IMAP4 Main)

GetLastErrorString Method

IMAP4 Main Object

Returns text description of the last error if available.

string GetLastErrorString();

Return Values

Returns the error description or an empty string if no description is available.

See Also

Standard Error Codes


IsConnected Method (IMAP4 Main)

IsConnected Method

IMAP4 Main Object

Returns the connection state of the object.

bool IsConnected();

Return Values

Returns non-zero if you are connected to the server.

See Also

Connect() Method
Disconnect() Method


Login Method (IMAP4 Main)

Login Method

IMAP4 Main Object

Logs in to the mail server using standard clear text authentication.

long Login(string strUser, string strPassword)

Parameters

String strUser

User Name

String strPassword

Users Password

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

See Also

Connect() Method
Logout() Method


Logout Method (IMAP4 Main)

Logout Method

IMAP4 Main Object

Logs out currently logged in user.

long Logout()

Parameters

None

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

See Also

Login() Method


Noop Method (IMAP4 Main)

Noop Method

Sends a NOOP command to the server.

long Noop()

Parameters

None

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

Remarks

Sending this command to the server causes it to reset any inactivity timers.

This command will update the MessageCount property and the Recent property.

See Also

MessageCount Property
Recent Property


RenameMailbox Method (IMAP4 Main)

RenameMailBox Method

IMAP4 Main Object

Renames an existing mailbox on the server.

long RenameMailBox(string strOldName, string strNewName)

Parameters

String strOldName

Name of existing mailbox.

String strNewName

New mailbox name.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

Remarks

Renaming the Inbox is permitted, and has special behavior. It moves all messages in the Inbox to a new mailbox with the given name, leaving the Inbox empty.

See Also

DeleteMailbox() Method
CreateMailbox() Method


SelectMailbox Method (IMAP4 Main)

SelectMailbox Method

IMAP4 Main Object

Selects a mailbox on the server.

long SelectMailbox(string strMailbox)

Parameters

string strMailbox

Name of mailbox to select. This can be taken directly from the Mailboxes collection object.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

Remarks

If this method is successful, the object will be placed in the selected state.

See Also

DownloadMailboxes() Method
Mailboxes Object


SetMessageFlags Method (IMAP4 Main)

SetMessageFlags Method

IMAP4 Main Object

Sets the flags of a message in the currently selected mailbox.

long SetMessageFlags(long nMsg, long nFlags, long nMethod, bool bUID);

Parameters

Long nMsg

The message number or unique ID.

Long nFlags

Flags to set for the message. May be zero or any combination of the following:

Value | Meaning
1 | Seen
2 | Deleted
4 | Flagged
8 | Answered
16 | Recent
32 | Draft

long nMethod

Tells how to change the flags. Can be either:

Value | Meaning
1 | Add the specified flags to any existing flags.
2 | Remove the specified flags if they exist.
3 | Replace the existing flags with the flags specified.

bool bUID

Specifies whether the value of nMsg is specified as a message number or unique ID. Set this parameter to non-zero if nMsg is specified as a unique ID.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

See Also

SelectMailbox() Method
Flags Property (IMAP4 Envelope Object)


Subscribe Method (IMAP4 Main)

Subscribe Method

IMAP4 Main Object

Subscribes to a mailbox.

long Subscribe(string strMailBox)

Parameters

string StrMailBox

Name of mail box to subscribe to.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

See Also

DownloadMailboxes() Method
SelectMailbox() Method
Unsubscribe() Method
MailBoxes Object


Unsubscribe Method (IMAP4 Main)

Unsubscribe Method

IMAP4 Main Object

Unsubscribes to a mailbox.

long Unsubscribe(string strMailbox)

Parameters

string StrMailbox

Name of mailbox to unsubscribe from.

Return Values

Returns zero if successful or one of the standard error codes if an error occurs.

See Also

DownloadMailboxes() Method
SelectMailbox() Method
Subscribe() Method
Mailboxes Object


OnAlert Event (IMAP4 Main)

OnAlert Event

IMAP4 Main Object

This event is fired if a command is completed successfully but there is an [ALERT] message in response.

OnAlert(string strMessage)

Parameters

string strMessage

The [ALERT] message sent by the server.


Status Event (IMAP4 Main)

Status Event

IMAP4 Main Object

Indicates the status of a pending operation.

Status(long nEvent, long nValue1, long nValue2);

Parameters

long nEvent

Specifies the event

long nValue1

The meaning of this parameter is specific to the value of nEvent. See the table below.

long nValue2

The meaning of this parameter is specific to the value of nEvent. See the table below.

nEvent | Description | nValue1 | nValue2
2 | Called when an "exists" tag is received from the server. | Number of the messages that exist in the selected mailbox. | 0- Not Used
3 | Called when a "recent" tag is received from the server. | Number of recent messages that exist in selected mailbox. This means that they have never been seen before. | 0- Not used
100 | Called when a message is being downloaded. | Number of bytes downloaded so far. | The total number of bytes to be downloaded.
101 | Reports status on envelopes being downloaded. | Envelope number downloaded. Will be set to 0 when Download is complete. | 0 - Not Used
102 | Called when message is being parsed. Fired twice once to begin and once to end. | When 1 message is starting to be parsed. When 0 message is complete. | 0 - Not used


IMAP4 Message Object

The IMAP4 Message object includes properties and methods used to examine and perform actions on a single message. To get a message into this object, call the DownloadMessage() method of the IMAP4 Main object.

Among its other properties, the Message object includes a Recipients property, an Attachments property and a MIMEParts property.

The Recipients property contains the IMAP4 Recipients collection object which can be used to manage the collection of recipients designated by the downloaded message.

The Attachments property contains the IMAP4 Attachments collection object which can be used to manage the collection of attachments to the downloaded message.

The MIMEParts property contains the IMAP4 MIMEParts collection object which can be used to manage the collection of MIME parts in the downloaded message.

See Also

IMAP4 Collection Objects
IMAP4 Recipients Object
IMAP4 Attachments Object
IMAP4 MIMEParts Object
DownloadMessage() Method


Attachments Property (IMAP4 Message)

Attachments Property

IMAP4 Message Object

This property contains the IMAP4 Attachments collection object.

Type: Object

See Also

IMAP4 Collection Objects
Attachments Object


BodyText Property (IMAP4 Message)

BodyText Property

IMAP4 Message Object

Contains the body text of the message.

Type: String

Remarks

The BodyText property is filled with the body text of the message.

A MIME message may contain multiple copies of body text in different formats, i.e. plain text, HTML and RTF. The BodyText property will contain only the first format specified in the message, which is usually plain text if it is available. The exact format of the BodyText property can be discovered by checking the values of the ContentType and ContentSubType properties.

All formats of body text in a MIME message are available through the MIMEParts collection object.

This property is read-only.

See Also

MIMEParts Object


MIMEParts Property (IMAP4 Message)

MIMEParts Property

IMAP4 Message Object

This property contains the IMAP4 MIMEParts collection object.

Type: Object

See Also

IMAP4 Collection Objects
MIMEParts Object


Recipients Property (IMAP4 Message, IMAP4 Envelope)

Recipients Property

IMAP4 Message Object, IMAP4 Envelope Object

This property contains the IMAP4 Recipients collection object.

Type: Object

See Also

IMAP4 Collection Objects
Recipients Object


TempMsgSourceFile Property (IMAP4 Message)

TempMsgSourceFile Property

IMAP4 Message Object

Contains the file name of the temporary message source file.

Type: String

Remarks

The message source file contains the entire message in RFC822 format.

The temporary message file is automatically deleted when the message is deleted from the object or the object is destroyed.

The location of this file is controlled by the TempDirectoy property of the IMAP4 Main object.

This property is read-only.


IMAP4 Attachments Object

The IMAP4 Attachments object is a collection object used to manage the collection of attachments to a message. The Item() method of this object, is used to access items in an array of IMAP4 Attachment objects. Each IMAP4 Attachment object can be used to examine and perform operations on an attachment to the message.

See Also

IMAP4 Collection Objects
IMAP4 Attachment Object
IMAP4 Message Object


IMAP4 Attachment Object

The IMAP4 Attachment object includes properties and methods used to examine and perform actions on a single attachment to the downloaded message.

See Also

IMAP4 Collection Objects
IMAP4 Attachments Object


FileName Property (IMAP4 Attachment)

FileName Property

IMAP4 Attachment Object

Contains the original filename of the attachment.

Type: String

Remarks

The FileName property contains the original filename of the attachment. This property does not indicate that the attachment is saved on disk at this time. To save an attachment to disk, use the Save() method.

If the file name can not be determined the filename "unknown.unk" will be used.

This property is read-only.

See Also

Save() Method


Name Property (IMAP4 Attachment)

Name Property

IMAP4 Attachment Object

Contains the name of the attachment.

Type: String

Remarks

This property is similar to the FileName property of the IMAP4 Attachment object, although they are both obtained from separate information specified in the attachment header. The value of this property is taken from the "Content-Type:" attachment header and is only relevant in MIME formatted messages.

The following attachment header shows that both filename and name are specified in the header. They are usually, but not always, the same.

Content-Type: application/x-zip-compressed; name="smtp.zip"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smtp.zip"

This property is read-only.

See Also

FileName Property


Save Method (IMAP4 Attachment)

Save Method

IMAP4 Attachment Object

Decodes and saves the attachment to disk.

long Save(string strFileName, bool bOverwrite)

Parameters

string strFileName

The path and filename of the destination file.

bool bOverwrite

Set this parameter to a non-zero value to overwrite the destination file if it already exists.

Return Values

Zero if successful, non zero if an error occurred.

Error Codes:

If the method fails, it will return one of the following error codes:

Value | Meaning
3 | Path not found
80 | File already exists

Remarks

If the object is running in a security context, that security context must have rights to create and write in the path specified in the strFileName parameter.


IMAP4 Recipients Object

The IMAP4 Recipients object is a collection object used to manage the collection of recipients designated by the downloaded message. The Item() method of this object, allows access to items in array of IMAP4 Recipient objects. Each Recipient object can be used to examine and perform operations on a recipient of the downloaded message.

See Also

IMAP4 Collection Objects
IMAP4 Recipient Object
IMAP4 Message Object


IMAP4 Recipient Object

The IMAP4 Recipient object includes properties and methods used to examine and perform actions on a single recipient of the downloaded message.

See Also

IMAP4 Collection Objects
IMAP4 Recipients Object


IMAP4 MIMEParts Object

The IMAP4 MIMEParts object is a collection object used to manage the collection of parts to a MIME message. The Item() method of this object, provides access to items in an array of IMAP4 MIMEPart objects. Each MIMEPart object can be used to examine and perform operations on a MIME part of of the downloaded message.

See Also

IMAP4 Collection Objects
IMAP4 MIMEPart Object
IMAP4 Message Object


IMAP4 MIMEPart Object

The IMAP4 MIMEPart object includes properties and methods used to examine and perform actions on a MIME part of the downloaded message.

See Also

IMAP4 Collection Objects
IMAP4 MIMEParts Object


ContentID Property (IMAP4 MIMEPart)

ContentID Property

IMAP4 MIMEPart Object

Contains the content ID of the MIME part.

Type: String

Remarks

The content ID is useful for referencing parts within the message. The value of this property is taken from the "Content-ID:" MIME part header.

This property is read-only.


ContentSubType Property (IMAP4 MIMEPart)

ContentSubType Property

IMAP4 MIMEPart Object

Contains the content sub type of the MIME part.

Type: String

Remarks

The ContentSubType property contains the sub content type which is extracted from the "Content-Type" MIME part header.

e.g. This sample content-type MIME part header record:

Content-Type: application/x-zip-compressed; name="smtp.zip"

would set the ContentSubType property to "x-zip-compressed"

This property is read-only.

See Also

ContentType Property


ContentType Property (IMAP4 MIMEPart)

ContentType Property

IMAP4 MIMEPart Object

Contains the content type of the MIME part.

Type: String

Remarks

The ContentType property contains the primary content type which is extracted from the "Content-Type" MIME part header.

e.g. This sample content-type MIME part header record:

Content-Type: application/x-zip-compressed; name="smtp.zip"

would set the ContentType property to "application"

This property is read-only.

See Also

ContentSubType Property


Description Property (IMAP4 MIMEPart)

Description Property

IMAP4 MIMEPart Object

Contains a textual description of the MIME part.

Type: String

Remarks

This property is read-only.


Encoding Property (IMAP4 MIMEPart)

Encoding Property

IMAP4 MIMEPart Object

Contains a description of the encoding of the MIME part.

Type: String

Remarks

This property describes the encoding algorithm used to encode the MIME part. For example Base 64 or Quoted Printable. The value of this property is taken from the "Content-Transfer-Encoding::" MIME part header.

i.e. The following excerpt from a MIME part header informs us that the MIME part was encoded using Base 64.

Content-Transfer-Encoding: base64

In this case, the Encoding property would be set to "base64".

This property is read-only.

See Also

Message Encoding


FileName Property (IMAP4 MIMEPart)

FileName Property

IMAP4 MIMEPart Object

Contains the filename of the MIME part.

Type: String

Remarks

If the MIME part is a file attachment, the FileName property contains the original filename of the attachment. This property does not indicate that the attachment is saved on disk at this time. To save an attachment to disk, use the Save() method.

If the file name can not be determined the filename "unknown.unk" will be used.

This property is read-only.

See Also

Save() Method


Headers Property (IMAP4 MIMEPart)

Headers Property

IMAP4 MIMEPart Object

Contains the full MIME part header.

Type: String

This property is read-only.


Name Property (IMAP4 MIMEPart)

Name Property

IMAP4 MIMEPart Object

Contains the name of the MIME part.

Type: String

Remarks

This property is similar to the FileName property of the IMAP4 MIMEPart object, although they are both obtained from separate information specified in the MIME part header. The value of this property is taken from the "Content-Type:" MIME part header.

The following MIME part header shows that both filename and name are specified in the header. They are usually, but not always, the same.

Content-Type: application/x-zip-compressed; name="smtp.zip"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smtp.zip"

This property is read-only.

See Also

FileName Property


Size Property (IMAP4 MIMEPart)

Size Property

IMAP4 MIMEPart Object

Contains the size of the MIME part.

Type: Long

Remarks

The Size property contains the size of the MIME part in its decoded state.

This property is read-only.


GetChunk Method (IMAP4 MIMEPart)

GetChunk Method

Gets a chunk of the MIME part data.

long GetChunk(long nIndex, long nSize, string strBuffer)

Parameters

long nIndex

Zero based Index to start reading from.

long nSize

Number of bytes to read. Should be between 0 - 65534.

string strBuffer

Buffer to place the read bytes.

Return Values

Number of bytes read or zero on error.

Remarks

If the number of bytes specified by the nSize parameter is greater than the number of bytes available, only the number of bytes available are read.

See Also

Save() Method


Save Method (IMAP4 MIMEPart)

Save Method

IMAP4 MIMEPart Object

Decodes and saves the MIME part to disk.

long Save(string strFileName, bool bOverwrite)

Parameters

string strFileName

The path and filename of the destination file.

bool bOverwrite

Set this parameter to a non-zero value to overwrite the destination file if it already exists.

Return Values

Zero if successful, non zero if an error occurred.

Error Codes:

If the method fails, it will return one of the following error codes:

Value | Meaning
3 | Path not found
80 | File already exists

Remarks

If the object is running in a security context, that security context must have rights to create and write in the path specified in the strFileName parameter.

See Also

GetChunk() Method


IMAP4 Mailboxes Object

The IMAP4 Mailboxes object is a collection object used to manage the collection of mailboxes. The Item() method of this object, provides access into an array of IMAP4 Mailbox objects. Each Mailbox object can be used to examine and perform operations on a mailbox on the IMAP4 server.

This collection object is filled when the DownloadMailboxes() method is called.

See Also

IMAP4 Collection Objects
IMAP4 Mailbox Object
DownloadMailboxes() Method


IMAP4 Mailbox Object

The IMAP4 Mailbox object includes properties and methods used to examine a mailbox located on the IMAP4 server.

See Also

IMAP4 Collection Objects
IMAP4 Mailboxes Object


Delimiter Property (IMAP4 Mailbox)

Delimiter Property

IMAP4 Mailbox Object

Specifies the character that is used to delimit mailbox levels.

Type: String

Remarks

The Delimiter property specifies the character which is used to delimit mailboxes levels on the server.

This property is read-only.


Flags Property (IMAP4 Mailbox)

Flags Property

IMAP4 Mailbox Object

Contains flags associated with mailbox.

Type: String

The following literal values are defined:

Value | Meaning
\Noinferiors | It is not possible for any child levels of hierarchy to exist under this name; no child levels exist now and none can be created in the future.
\Noselect | It is not possible to use this name as a selectable mailbox.
\Marked | The mailbox has been marked "interesting" by the server; the mailbox probably contains messages that have been added since the last time the mailbox was selected.
\Unmarked | The mailbox does not contain any additional messages since the last time the mailbox was selected.

Remarks

If multiple flag values apply, they will be concatenated and separated with a space.

If it is not feasible for the server to determine whether the mailbox is "interesting" or not, or if the mailbox is a \Noselect mailbox, the server should not send either \Marked or \Unmarked.


Name Property (IMAP4 Mailbox)

Name Property

IMAP4 Mailbox Object

Name of the mailbox.

Type: String

Remarks

Includes delimiter if mailbox is not top level.


IMAP4 Enveolpes Object

Envelopes Collection Object

The IMAP4 Attachments object is a collection object used to manage a collection of Envelope objects. Each Envelope object can be used to examine various properties of messages on the IMAP4 server.

This collection object is filled when the DownloadEnvelopes() method is called.

See Also

IMAP4 Collection Objects
IMAP4 Envelope Object
DownloadEnvelopes() Method


IMAP4 Envelope Object

The IMAP4 Envelope object includes properties and methods used to examine the properties of messages located on the IMAP4 server.

See Also

IMAP4 Collection Objects
IMAP4 Envelopes Object


Date Property (IMAP4 Envelope)

Date Property

IMAP4 Envelope Object

Contains the date and time of the the message as stored on the server.

Type: String

Remarks

This property contains the date and time of the message on the server. This may be different from any RFC-822 dates specified inside the message headers.

This property is read-only.


Flags Property (IMAP4 Envelope)

Flags Property

IMAP4 Envelope Object

Specifies flags set on message.

Type: Long

May be any combination of the following:

Value | Meaning
1 | Seen
2 | Deleted
4 | Flagged
8 | Answered
16 | Recent
32 | Draft

This property is read-only.


IMAPID Property

IMAP4 Envelope Object

Specifies unique ID of this message on the IMAP4 server.

Type: Long

Remarks

See the section on the IMAP4 protocol for more information on IMAP4 IDs.


Mail Dialogs Introduction

Mail Dialogs

The EasyMail Mail Dialogs allow your application to display rich, contemporary e-mail dialog boxes within your application with only one line of code.

Two dialogs are currently supported: composition / editing and viewing.

The dialog functionality is totally encapsulated inside a separate dialog module dll. By separating the dialog functionality into another dll, the core objects remain small and fast.


The Dialog Module

The dialog module is a Windows dll file which contains the resources and the code to display the mail dialogs.

If you will be using the mail dialogs in your application, you must distribute the dialog module dll with your application.

See the section on distribution for more information on distributing and installing the dialog module.

The dialog boxes can be translated into different languages by editing the dialog module. See the section on mail dialogs internationalization for more information on this topic.


Message Composition and Editing Dialog

The mail composition and editing dialog is used to create or edit an e-mail message.

The dialog is launched from the SMTP object. See the DoSendDlg() method form more information.


Message Viewing Dialog

The mail message viewing dialog is used to view an e-mail message.

The dialog may be launched from the POP3 or IMAP4 objects. See the DoViewDlg() method form more information.


Mail Dialogs Internationalization

The dialog module contains the resource data for the dialogs. The resource data contains all the literal text used by the dialogs and their associated routines. The dialog module can therefore be edited and translated into any desired language.

To edit the dialog module, you will need a Windows resource editor. Editing a resource is an advanced development topic. It is not recommended that you edit the dialog module resources unless you know what you are doing. Quiksoft does not offer support for the the editing the resources of the dialog module.


MessagePrinter Object Introduction

The message printer object allows you to send an e-mail message to a system printer.

The object allows you to customize the look of the printout and optionally add control information such as page numbers and routing information. A printer may be preassigned or selected by the user at runtime.

Sample printout:


Mesage Printer Usage

ProgID | EasyMail.MessagePrinter.4
CLSID | E802F232-E149-11D2-B41B-00A0CC3A50B9

EasyMail MessagePrinter is a lightweight COM object which which allows you to send Internet e-mail to a system printer. It can be used for server side processing in ASP files, and Perl scripts. It can also be used in any other COM compatible application. i.e.: Internet Explorer, VB, Delphi, etc...

License Keys

The MessagePrinter object does not have a LicenseKey property. Since the object obtains message information from the other EasyMail objects, it relies on their license keys for license validation.

Usage in your application development system:

In order to use the object, you will have to create it in your code. The MessagePrinter object is used like an OLE Automation server or COM object. Although the method for creating an COM object is different within each development system, they all support it.

In VB the command to create an object is "CreateObject()" and is used like this:

Set PrinterObj = CreateObject(EasyMail.MessagePrinter.4")

After the object is created, you can access all of its properties and methods as usual.

The object gets the message data from one of the other EasyMail objects such as the POP3 or IMAP4.

Here is an example of printing a message contained in the POP3 object:

'Create both objects
Set POP3=CreateObject("EasyMail.POP3.4")
Set PrintObj=CreateObject("EasyMail.MessagePrinter.4")

...
Populate the POP3 object by downloading
Messages or loading them from local files
...

'Print the first message
hMsg=POP3.Messages(1).CreateMessageHandle()
PrinterObj.PrintMessage(hMsg, 511)


Header Property (MessagePrinter)

Header Property

MessagePrinter Object

Sets a header to be printed at the top of the first page.

Type: String

Remarks

This property specifies text to be printed at the top of the first page. Carriage returns and linefeeds (chr(13) & chr(10)) may be embedded in the text.

The header is useful for printing routing information or a description of the message at the top of each printout.

See Also

HeaderFlags Property


HeaderFlags Property (MessagePrinter)

HeaderFlags Property

MessagePrinter Object

Sets the header options.

Type: Long

May be zero or any combination of the following values:

Value | Meaning
1 | Align center (if not specified, the text aligns left)
2 | Bold
4 | Draw a line under the header

Remarks

The header is printed in a system chosen font and size.

See Also

Header Property


LeftMargin Property (MessagePrinter)

LeftMargin Property

MessagePrinter Object

Sets left margin in points.

Type: Long

See Also

RightMargin Property
TopMargin Property


Printer Property (MessagePrinter)

Printer Property

MessagePrinter Object

Selects the printer to use for output.

Type: String

Remarks:

Must be the name of a valid system printer.

This value is ignored if the "show printer dialog" option is selected when calling the PrintMessage() method.

See Also

GetPrinterName() Method
PrintMessage() Method


RightMargin Property (MessagePrinter)

RightMargin Property

MessagePrinter Object

Sets right margin in points.

Type: Long

See Also

LeftMargin Property
TopMargin Property


TabLength Property (MessagePrinter)

TabLength Property

MessagePrinter Object

Sets the number of spaces to print when a tab character is encountered.

Type: Long

Remarks:

The value of this property defaults to 5.


TopMargin Property (MessagePrinter)

TopMargin Property

MessagePrinter Object

Sets top margin in points.

Type: Long

Remarks:

The bottom margin is automatically set and can not be changed.

See Also

LeftMargin Property
RightMargin Property


CountPrinters Method (MessagePrinter)

CountPrinters Method

MessagePrinter Object

Returns the number of printers available.

long CountPrinters(long nReserved)

Parameters

long nReserved

Reserved, should be set to zero.

Return Values

Returns the number of available printers, or zero if an error occurs. Call the GetLastError() method to an extended error code.

See Also

GetPrinterName() Method
Printer Property


GetLastError Method (MessagePrinter)

GetLastError Method

MessagePrinter Object

Returns an error code pertaining to the last printer error encountered.

long GetLastError()

Parameters

None

Return Values

Returns one of the following error codes:

Value | Meaning
200 | No printers
201 | Invalid value
202 | Invalid printer
203 | Could not initialize printer
204 | Could not write to printer
205 | Cancelled by user


GetPrinterName Method (MessagePrinter)

GetPrinterName Method

MessagePrinter Object

Returns the textual name of a printer.

string GetPrinterName(long nPrinterNum)

Parameters

long nPrinterNum

The numerical index of the printer. This parameter must be between 1 and the value returned by the CountPrinters() method. This method will return an error unless the CountPrinters() method is called first.

Return Values

Returns the name of the printer or an empty string if an error occurs. Call the GetLastError() method to an extended error code.

See Also

CountPrinters() Method
Printer Property


PrintMessage Method (MessagePrinter)

PrintMessage Method

MessagePrinter Object

Prints a message.

long PrintMessage(long hMsg, long nOptions)

Parameters

long hMsg

A message handle.

long nOptions

May be zero or any combination of the following values:

Value | Meaning
1 | Include "subject" in message header
2 | Include "to" in message header
4 | Include "date" message header
8 | Include "from" message header
16 | Include "body text" in printout
32 | Print the current time and date at the bottom of each page
64 | Print page numbers at the bottom of each page
128 | Show printer dialog. This option allows the user to select the destination printer and ignores any value set in the Printer property.
256 | Include "attachment names" in message header

The constant 511 is the sum of the values and thus turns on all options.

Return Values

Returns zero if successful or one of the following error codes if an error occurs:

Value | Meaning
202 | Invalid printer
203 | Could not initialize printer
204 | Could not write to printer
205 | Cancelled by user

See Also

CreateMessageHandle (POP3 Message, IMAP4 Message)


SetFont Method (MessagePrinter)

SetFont Method

MessagePrinter Object

Sets the font of the message body.

string SetFont(string strName, long nSize, long nStyle)

Parameters

string strName

The name of the font to select.

long nSize

The size of the font in points.

long nStyle

The style of the font. May be zero or any combination of the following values:

Value | Meaning
1 | Bold
2 | Italic
4 | Underline

Return Values

Returns zero if successful or 1 if an error occurred. If an error occurs, the font is automatically set to a system font.

This method only sets the font of the message body text. The font of the message header information can not be changed.

If an invalid font name is passed as the strName parameter, the system will attempt to automatically select a font for you and may not return an error. Make sure that you specify the font name exactly as it appears in the font list to avoid this behavior.


Glossary

APOP

An authentication mechanism designed to protect your POP3 account password. APOP authentication does not require your account password to be sent as plain text to the POP3 mail server. See the POP3 Object's AuthMode property for more information on APOP.

Attachment Header

A block of text, preceding an attachment, used to describe the attachment. The header may take different forms depending on the format of the message. See the subject on headers for more information.

Base 64

A method of encoding data, often used to encode message body text and file attachments to mail messages. For more information, click here.

Blind Carbon Copy

A blind carbon copy recipient, receives a copy of the message, however their address does not appear in the CC: list of the message.

CLSID

Class ID. Class IDs are used by the system registry to uniquely identify objects. The CLSID of the SMTP object is: DB034511-047C-11D2-80FA-00AA00336A3E.

Collection Object

An object which contains properties and methods used to maintain and iterate through a collection of data. For more information about collection objects, see the topic on the POP3 collection objects.

COM Object

An object which conforms to the Microsoft Component Object Model. Sometimes referred to as an OLE object. COM objects expose properties and methods which may be accessed by other applications. When another application uses the resources provided by a COM object, that application inherits the functionality programmed into the object.

Dialog Module

The DLL file which contains the functionality to display the mail dialogs supported by the EasyMail Objects. Click here for more information.

ESMTP

Extended SMTP. ESMTP represents several extensions to the SMTP protocol. For more information on ESMTP click here.

Firewall

A hardware or software device which regulates data flow in and out of a private network. For more information on firewalls click here.

IMAP4

Internet Message Access Protocol Version 4. The IMAP4 protocol is used to preview and fetch messages from a mail server.

Inbox

The Inbox is a special IMAP4 mailbox used to place all incoming mail. See the section on the IMAP4 Protocol for more information on the Inbox.

License Key

A text string, provided by Quiksoft, which is assigned to the object's LicenseKey property to take it out of demo mode. License keys are uniquely generated for each product and licensee. For more information on license keys click here.

Message Header

A block of text at the beginning of the mail message which describes some property of the message. See the topic on message headers for more information.

MIME

Multipurpose Internet Mail Extensions. MIME is used to delineate and describe the different parts of an e-mail message. For more information on MIME, click here.

MIME Part

An individual part of a MIME message.

MIME Part Header

A descriptive block of text prepended to a MIME part. See the subject on headers for more information.

OCX

A form of COM Object which supports manipulation and monitoring through properties, methods and events. OCX objects usually support visual editing.

ODE

Object Data Exchange. A mechanism which allows the EasyMail Objects to efficiently exchange data.

OLE Automation Server

A form of COM Object which supports manipulation and monitoring through properties, methods and events.

ProgID

Program ID. A friendly name used to uniquely identify an object. The system registry maps CLSIDs to ProgIDs. This allows objects to be identified by a friendly and easier to remember name. The ProgID of the SMTP object is EasyMail.SMTP.4

POP3

Post Office Protocol Version 3. Used by mail readers to retrieve mail from a mail server. For more information, see the POP3 Protocol topic.

Port

A connection point to a computer used with the TCP/IP protocol.

Protocol

A method of sending and receiving data.

Quoted Printable

A method of encoding data, often used to encode message body text. For more information, click here.

RFC

Request For Comment. A document outlining a standard, a proposed standard, or proposed changes to an existing standard. For a list of RFCs supported by the EasyMail Objects, click here.

Security Context

The collective access rights of a system login. If the object is running under a system user account, such a Windows NT login, the security context is the collective properties of that user account. For more information on this topic, click here.

SMTP

Simple Mail Transport Protocol. Used to send mail to and between mail servers. See the SMTP Protocol topic for more information.

EasyMail SMTP Express

A message queuing system which intercepts mail transmissions from the SMTP object and sends them in the background. This allows the SMTP object to operate very quickly. For more information on SMTP Express, visit the EasyMail section of our website at http://www.quiksoft.com/easymail.

TCP/IP

Transmission Control Protocol / Internet Protocol. This is the primary protocol used on the Internet.

Type Library

A type library is a binary file which contains information about an objects properties, methods and events. The type library for each EasyMail Object is embedded in the object's DLL, so a separate file is not necessary.

UUencode

A method of encoding data, often used to encode file attachments in mail messages. For more information, click here.


Legal Notices

©1997-1999 Quiksoft Corporation. All Rights Reserved. Unauthorized duplication or distribution prohibited.

Quiksoft, EasyMail and SMTP Express are trademarks of Quiksoft Corporation. Other trademarks mentioned are the property of their legal owner.


Tag Property (POP3)

Tag Property

POP3 Main Object

The tag property is not processed by the object and may be used for user defined purposes.

Type: String


TempFileName Property (POP3 Main)

TempMsgSourceFile Property

POP3 Main Object

The fully qualified path and filename of the temporary message file.

Type: String

Remarks

This property is only valid if the previous call to the DownloadMessages() method was called with the "Save Full Message Source" option selected. If the this option was not specified during the call to DownloadMessages(), this property will return NULL.

The temporary message file does include attachment data.

See Also

DownloadMessages Method


POP3 Version History

3,0,0,5 August 27, 1998

Fixed error encountered when decoding zero-length UUencoded attachments.

Added LoadMessage() method, which loads and parses an e-mail message from a file.

Added ability to decode header fields that use non-ASCII characters, as specified in RFC 1522 "Message Header Extensions for Non-ASCII Text" NOTE: The character set name used to originally encode the text is disregarded because there is no way to easily return it via the object.

3,0,0,2 July 23, 1998

Added the functionality to decode message body text, encoded with Base 64.

3,0,0,0 July 10, 1998

Initial release.


Quiksoft Web Site

Visit the Quiksoft web site for information, support and product updates.

General Information

http://www.quiksoft.com

EasyMail

http://www.quiksoft.com/easymail

Technical Support

http://www.quiksoft.com/support


SMTP

Simple Mail Transport Protocol

The protocol used to send mail to a recipient on the Internet.


Tag Property (SMTP)

Tag Property

SMTP Object

The tag property is not processed by the object and may be used for user defined purposes.

Type: String


SMTP Version History

3,0,0,4 - August 27, 1998

Added the proper functionality to handle parenthetical comments inside e-mail addresses.

Improved the performance of the SubmitToExpress() method.

The capitilazation of the ReplyTo property name was corrected.

3,0,0,1 August 3, 1998

Fixed problem when UUencoding some files.

Priority headers are no longer added, unless you specify a value for the Priority property.

3,0,0,0 July 10, 1998

Initial Release


Version3

What's New in Version 3

Version 3 of our EasyMail Objects, represents a landmark release for Quiksoft. Due to the overwhelming success of the objects, we have spent much of our time, combing through the objects, looking for ways to make them even better.

Our design goals were to:

  • Make the objects easier to use

  • Streamline code to allow the objects to run faster
  • Streamline memory allocations so the objects use less memory
  • Increase the stability of the objects

We feel that we have met these goals with this new release. We will continue to concentrate on these areas with great vigor throughout all future releases.

In addition to improving the efficiency of the objects, we have also added new features.

Documentation

Version 3 ships with a help system designed in Microsoft HTML Help format. The help system contains, sample code, background information on e-mail technologies, and full reference materials on the EasyMail Objects

Royalty Free Distribution

When you license the EasyMail Objects, you are permitted to distribute them with your applications royalty free. For all the details, see the Royalty Free License Agreement.

Properties and Methods Renamed

Based on user feedback, and our own study, we found that some property and method names were not accurately descriptive of the data they described or the functions they invoked. To solve this problem, we have renamed some of the properties and methods. This should make the objects much easier to use and help to avoid any confusion in the future.

Memory Management

We have always boasted about our objects efficient use of memory. Our memory management routines have all been reevaluated and improved significantly. Memory consumption was reduced by almost 50%.

Mission Critical Design

From the first release of EasyMail Objects, mission critical design, has been our forte and claim to fame. Our objects stand clear above pack when dependability is at stake. Version 3, contains our CodeNet™ technology, which prevents the objects from crashing in the event of an abberent message.

EasyMail SMTP Express™ Message Queuing System

Version 3 of the SMTP Object includes integration support for our new EasyMail SMTP Express™ message queuing system. EasyMail SMTP Express intercepts messages created with the EasyMail SMTP Object and queues then for transmission in the background. This allows the SMTP object to send mail at a very fast rate. EasyMail SMTP Express can run either as a system-tray application or as a service if installed on Windows NT. EasyMail SMTP Express is available as a separate product from Quiksoft. For more information on EasyMail SMTP Express, visit the EasyMail section of our website at http://www.quiksoft.com/easymail.

Compatibility with Previous Releases

Instead of compromising ease of use and functionality, version 3 of the EasyMail objects is not 100% compatible with past releases. We are sure that these changes will make the objects much easier and intuitive.

General Changes

If you have purchased a license key for a previous version of the EasyMail Objects, a new license key will be required for version 3. To make things easier, we have come up with a much more simplified license key. One key can be used with all of the EasyMail objects and applications.

SMTP Object Changes

New CLSID | DB034511-047C-11D2-80FA-00AA00336A3E
New ProgID | EasyMail.SMTP.3
New filename | emsmtp.dll
Attach Method | Renamed to AddAttachment Options parameter added
AutoWrap Property | Defaults to 76
Message Property | Renamed to BodyText
HTML Property | Renamed to BodyFormat
ImportMessage Method | Renamed to ImportBodyText
MIMEOptions Property | Renamed to BodyEncoding Option 4 was removed and is now handled by the AddAttachment method (formerly called Attach)
GetFormattedMessage Method | Renamed to GetWrappedBodyText
AddCustomType Method | Renamed to AddCustomHeader
UUencode property | Renamed to Encoding

POP3 Object Changes

New CLSID | 3115D15B-05F1-11d2-8103-00AA00336A3E
New ProgID | EasyMail.POP3.3
UI property (POP3 Main) | Renamed to DemoMode
Server property (POP3 Main) | Renamed to MailServer
PreferredType property (POP3 Main) | Renamed to PreferredBodyFormat
Threshold property (POP3 Main) | Removed. All message data is now temporarily stored on disk. See the TempDirectory property for more information.
SaveAll property (POP3 Main) | Removed. All attachment data is now temporarily stored on disk. See the TempDirectory property for more information.
Download method (POP3 Main) | Renamed to DownloadMessages
FullMessageFilename property (POP3 Message) | Renamed to TempMsgSourceFile
Message event (POP3 Main) | Renamed to StatusMessage
MessageFlag property (POP3 Message) | Renamed to to MessageStatusFlag
MessageTxt property (POP3 Message) | Renamed to BodyText
Save method (POP3 Attachment) | Added "Overwrite" parameter
Type property (POP3 Attachment) | Renamed to ContentType
SubType property (POP3 Attachment) | Renamed to ContentSubType


Version 4

What's New in Version 4

IMAP4 Object

EasyMail now supports IMAP4 (Internet Message Access Protocol version 4 rev 1). See the sections on the IMAP4 protocol and the reference section on the IMAP4 object for more information.

SMTP Object

New Options

OptionFlags Property

Sets various SMTP options.

Extended SMTP (ESMTP) Support

ESMTP_Pipelining Property | Enables / disables ESMTP pipelining.
ESMTP_DSN_Notify Property | Controls what events trigger ESMTP delivery status notifications.
ESMTP_DSN_Return Property | Controls how much of the original message is returned with ESMTP delivery status notifications.
ESMTP_DSN_ID Property | Specifies the ESMTP delivery status notification id for a message.

POP3 Object

We have packed more functionality into the POP3 object, to better enable you to manage large mailboxes.

DeleteSingleMessage() Method | Deletes a single message from the server without downloading it.
DownloadSingleMessage() Method | Downloads a single message from the server.
DownloadSingleMessageHeaders() Method | Downloads the headers of a single message from the server.
GetMessageID() Method | Returns the servers unique id for a given message.
GetMessageNumFromID() Method | Returns the ordinal position of a message given its unique id.
GetMessageSize() Method | Returns the size of a message on the server.
GetSocketHandle() Method | Returns the socket handle of the current connection with the server.

If you are upgrading from a release prior to version 3, click here to find out what was added in version 3.